Troubleshooting & FAQ#
“Please set the Immich server URL and API key in settings first.”#
You’ll see this whenever a gallery, upload, or delete action is attempted using a profile whose server URL and/or API key aren’t both filled in yet, or when no profile is configured at all, under Settings → Harang Immich. Fill in both fields for your active profile (or add one) and try again.
“Failed to fetch image list”, “Failed to load thumbnail”, “Failed to load original image” (with an HTTP status code)#
These indicate the request reached your Immich server but it returned an error. Common causes:
The API key is invalid, expired, or was revoked in Immich.
The server address is wrong (check for a missing
https://or a stray trailing path).The selected album no longer exists (re-open the settings tab so the album dropdown refreshes, or select
(All photos)).
“Upload failed” / “Upload response is missing an asset id”#
The upload request either failed on the server side (check the status code against your Immich server logs) or Immich responded without the expected asset ID. Verify the server URL/API key, and that the account has permission to upload to the selected album.
An image shows a broken/error placeholder in the note#
This means the note contains a valid Harang Immich link, but fetching that specific asset’s thumbnail failed (for example, the asset was deleted directly on the Immich server outside of Obsidian). Hover the broken image for the underlying error message.
An image shows a “profile not found” error#
The link’s embedded profile name doesn’t match any profile currently in Settings → Harang Immich. This happens for one of two reasons:
That profile was deleted. Re-add a profile with the same server and the exact same name if you want these images to work again.
That profile was renamed. The link is still looking for the old name. Renaming a profile back to what it used to be called fixes every image that broke because of the rename.
There’s no way to recover the original link target once a profile is deleted or renamed away from the name a link was pointing at — the name is the link’s only reference to it.
An image doesn’t render as an image at all#
Harang Immich only renders its own dedicated link syntax — plain Markdown
image syntax () is not affected by this plugin. Make sure the
link uses the exact form ![immich:profile name/ASSET_ID] or
![immich:profile name/ASSET_ID|alt text] (older links without the
profile name/ part are also valid, see Usage). This syntax is
normally inserted for you automatically; if you’re typing it by hand, double
check for typos such as a stray space or parenthesis.
Cache keeps growing / I want to free up space#
Thumbnails are cached locally so they don’t need to be re-downloaded from Immich on every view. Open Settings → Harang Immich and use Clear cache under Cache management. This only removes local cache files — it does not delete anything from your Immich server.
Images fail to load only on mobile#
Harang Immich uses Obsidian’s requestUrl API specifically to avoid CORS
issues that would otherwise affect Obsidian Mobile when talking to a
self-hosted Immich server. If images still fail only on mobile, check that
your mobile device can actually reach the Immich server address (e.g. it may
need a VPN or be on the same local network), independent of the plugin.
Deleting a note doesn’t ask what to do with its images#
The delete-confirmation prompt only appears if the note actually referenced one or more Harang Immich links at the time it was deleted, renamed, or edited. Notes containing only ordinary Markdown images or no images at all won’t trigger it.