Headless troubleshooting

Open beta

Login or MFA prompt

Run ob login only after exact account approval and with credential-bearing options omitted. The owner or approved managed test-account operator completes the interactive prompts. Stop if login would switch accounts, credentials would enter logs/chat/CI, or the approved operator is absent.

Subscription unavailable

Headless Sync and Publish require active subscriptions. Do not buy, enable, renew, upgrade, or change billing as a troubleshooting step. Record the approved account alias and entitlement as unknown or blocked and stop.

ob is not found

• Confirm Node.js 22+ and npm are available.
• Install obsidian-headless globally.
• Inspect npm's global binary directory and add it to PATH.
• Restart the terminal and retry ob --help.
• Keep the docs site's Node 20.x build runtime separate from the Headless runner.

Wrong local path or setup

Use ob sync-list-local and read-only ob sync-status to inspect mappings. Stop before setup, unlink, path, device, config-directory, mode, conflict, file-type, config-group, or exclusion changes. Require backup and exact scope approval.

Continuous process stops or loops

Run continuous Sync under a supervisor with bounded redacted logs, health checks, restart limits, and a stop/disable procedure. Do not infer convergence from process uptime or ob sync-status; perform second-device exact file/content/hash readback and conflict/deletion checks.

Conflicts or unexpected changes

Stop Sync, preserve both copies and evidence, and route resolution to the named recovery owner. pull-only ignores local edits; mirror-remote reverts local edits. Do not change modes without a backup and explicit approval.

Two sync methods on one device

Do not run desktop Sync and Headless Sync on the same device. Stop one method and reconcile through the approved recovery plan before continuing.

Unlink consequences

ob sync-unlink disconnects a vault and removes stored credentials. ob publish-unlink disconnects Publish. ob logout clears stored account credentials. Each requires exact approval and a rollback plan.

Linux creation times

The official Headless Sync page says Linux does not support the native birthtime addon; Sync otherwise operates normally. Do not treat creation-time differences alone as missing file content. Compare exact paths, bytes/content, and hashes.

Beta fallback

If an open-beta defect blocks a safe run, stop the Headless process, preserve non-secret diagnostics, restore the known-good projection from backup, and route the need through desktop Sync/File Recovery or a separately verified provider workflow. Do not invent Headless history or restore commands.

Sources: Obsidian Headless and Headless Sync, retrieved 2026-08-29 EDT.