Resolving an Unable to Resolve Link Error for Org Mode in Emacs

Documenting to Share a Solution

I’ve been dabbling with the org-transclusion package. But I encountered an odd behavior somewhere in my org-mode and org-roam configuration.

What Worked and What Didn’t

I had a source org file. I linked to the target org file in another directory via the target’s id property.
In my source I had the equivalent of [[id:org-id-get-create][Name of Target]]. The org-id-get-create is a placeholder (and the name of the function I used to generate the target’s ID).

When I would open the target link in my buffer, I would jump to the target document. As expected.

However, when I attempted to use the org-transclusion functions or export (via org-export-dispatch) the org document to another format, I got the following error:

Unable to resolve link: org-id-get-create

I thought this had something to do with my directory structure. But it worked to link to other files in the same directory as the target.

Poking Around Through Source Code

I tried rebuilding my org-roam database (e.g., M-x org-roam-db-clear-all then M-x org-roam-db-sync) but that didn’t work.

In the source file, I ran org-lint. That generated reported what looked to be the same error message.

So I dug further into the org-lint method. There I learned about the org-lint--checkers variable.
The registered functions that are called to lint a document.
I went looking through that list and found a likely culprit: org-lint-invalid-id-link.

The org-lint-invalid-id-link function lead me to the org-id-find function. Which in turn called org-id-find-id-file id. And there I found the following code bit of code: (unless org-id-locations (org-id-locations-load)).

Huzzah! Org-mode was generating a cache! Somewhere there must be a cache invalidation or update function.

So I went looking for functions like the org-id-locations-load. I found org-id-update-id-locations and org-roam-update-org-id-locations.

I ran the org-id-update-id-locations and it reported processing several files, but certainly not enough. I thenorg-roam-update-org-id-locations; that function call reported a lot of processed files.

Hoping that this update of a cache would resolve my problem, I went back to the previously broken source document. Both org-transclusion and org-export-dispatch worked.

Capturing the Knowledge

I wrote a function that is now part of Emacs configuration; the purpose of the function is to help remind me how to fix this problem if it shows up again.

;; I encountered the following message when attempting
;; to export data:
;;
;; "org-export-data: Unable to resolve link: FILE-ID"
(defun jnf/force-org-rebuild-cache ()
  "Rebuild the `org-mode' and `org-roam' cache."
  (interactive)
  (org-id-update-id-locations)
  ;; Note: you may need `org-roam-db-clear-all'
  ;; followed by `org-roam-db-sync'
  (org-roam-db-sync)
  (org-roam-update-org-id-locations))

I don’t envision running that function all that much, but it will be a bit of written memory of this debugging.

Conclusion

First, navigating Emacs functions is amazing. Emacs provides powerful introspection.

I used helpful.el to jump to the documentation of a function, and kept jumping deeper. I used M-x paired with marginalia.el to look for similar named functions.

Pairing helpful.el and marginalia.el (and many other packages), I could do ever narrowing work and when I needed to expand my focus.

In fact, it was so easy to navigate I did it twice. First when debugging and then when writing this blog post.

Second, taking the time to write this up, I hope I help other folks (including my future self).