`getAbstractFileByPath` does not function as expected

Developers: Plugin & API
1

Expected

  • using getAbstractFileByPath during Plugin.onload should return a TFile or TFolder instance when provided with a valid existing path

Actual

  • it returns null

Notes

Multiple other users have documented issues related to this:

  • https://forum.obsidian.md/t/vault-getabstractfilebypath-keeps-returning-null-and-im-unsure-why/37246
  • https://discord.com/channels/686053708261228577/840286264964022302/973383532883890186
  • https://discord.com/channels/686053708261228577/840286264964022302/1198687020856385556
  • https://discord.com/channels/686053708261228577/840286264964022302/902957459675680828
  • https://discord.com/channels/686053708261228577/840286264964022302/844681863967670342
  • https://discord.com/channels/686053708261228577/840286264964022302/1075457513367011398
  • https://discord.com/channels/686053708261228577/707816848615407697/833404792322654268

This behavior is not documented at any of these relevant locations:

  • https://docs.obsidian.md/Reference/TypeScript+API/Vault/getAbstractFileByPath
  • https://docs.obsidian.md/Reference/TypeScript+API/FileView/onload
  • https://docs.obsidian.md/Plugins/Getting+started/Anatomy+of+a+plugin#Plugin+lifecycle
  • https://docs.obsidian.md/Reference/TypeScript+API/Workspace/onLayoutReady
  • https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines#Prefer+the+Vault+API+over+the+Adapter+API

The user-proposed workaround of using onLayoutReady does not fully resolve potential use cases of getAbstractFileByPath. For example, a MarkdownPostProcessor which requires a Grammar.wasm asset to be resolved during Plugin.onload. Moving the registration of the MarkdownPostProcessor to onLayoutReady results in unprocessed documents when opening an Obsidian workspace with target files already loaded.

Additionally, this seems outside of the scope of onLayoutReady in terms of expectations based on the naming convention and present documentation. One could reasonably expect that either: [A] (preferably) the getAbstractFileByPath should provide up-to-date access of the file system during Plugin.onload, or [B] there should be a documented general onReady hook or a more specific onVaultReady hook.

Based on a few user comments [1, 2] it seems like the Vault API is dependent on a cache which has not been fully initialized when onload is executed. As such, it might not be the best approach for cases like the asset-based post-processor I described above, and developers might be better off using the Adapter API in such scenarios. If that is the case, the documentation should be updated to provide more clarity and information about these usage scenarios.

Additionally, if getAbstractFileByPath is used before the cache has been initialized, it would be incredibly helpful if it threw an error or at least logged a warning. The behavior of returning null silently has caused myself and others a significant amount of unnecessary debugging time, as evidenced by personal experience and the number of related issues I provided. The current documentation does not establish an expectation that it will work in some cases and not others.

2 Likes