Troubleshooting & FAQ

Troubleshooting & FAQ#

“Connection failed” when testing a profile#

Symptom: clicking Test connection & auto-discover shows a “Harang contacts: Connection failed - …” notice.

Cause: most commonly one of:

  • The Server URL is wrong, unreachable, or missing the https:// scheme.

  • The username or password is incorrect.

  • The server doesn’t support the standard CardDAV discovery chain (current-user-principal → addressbook-home-set) and isn’t pointed directly at an address book collection either.

Fix: double-check the credentials, and if discovery keeps failing, try pointing Server URL directly at the address book collection URL instead of the server root (for example Nextcloud’s https://<host>/remote.php/dav/addressbooks/users/<user>/contacts/).

A chip looks faded with a dashed border (“unresolved”)#

Symptom: a {{hrcard:...}} chip renders with reduced opacity and a dashed border instead of a normal filled chip.

Cause: the plugin could not find a matching contact in its current cache. This happens when the referenced contact was deleted from the server, when the local cache simply hasn’t been refreshed since the note was written, or when the reference was typed by hand with a profile name/UID that doesn’t actually exist (see Architecture - the syntax stores profile name + CardDAV UID, not the display name, so a hand-typed reference needs the exact UID to resolve at all).

Fix: run the Refresh contacts command (or click Refresh in settings), then reopen the note. If the chip is still unresolved after a refresh, delete it and re-insert it via the {{hrcard: autocomplete popup instead of typing it by hand.

The plugin doesn’t appear after installing#

Fix: confirm main.js, manifest.json, and styles.css are directly inside <vault>/.obsidian/plugins/harang-contacts/ (not a subfolder), that the plugin is enabled under Settings → Community plugins, and that Obsidian is on version 1.13.4 or later (see Prerequisites). Fully restart Obsidian after installing or updating the files.

The plugin doesn’t update after git pull#

Symptom: you pulled the latest source changes, but Obsidian still behaves like the old version.

Cause: installing from source requires an explicit rebuild and a manual copy step — pulling new source alone does not update the files Obsidian actually loads.

Fix: run the full update sequence from Installation, Method 3:

git pull
npm install
npm run build

Then copy the freshly built main.js (and manifest.json/ styles.css if they changed) into <vault>/.obsidian/plugins/harang-contacts/ again, and restart Obsidian.