Troubleshooting & FAQ

The app won't load / stuck on "Loading…" / templates & sample KB missing

Most common cause: you opened the file directly as file://…/app/index.html. Browsers block fetch() on the file:// protocol, so the app can't load its sample KB or templates.

• Fix: serve over HTTP. From the project folder run python3 -m http.server 8000 and open http://localhost:8000/app/index.html. See Self-hosting.
• If templates won't load but the app otherwise works: same root cause — the Templates button says "Templates still loading…". Serve over HTTP and reload.
• If you self-host on a subpath and assets 404: confirm you kept the folder structure intact (the app uses relative paths like ../assets/…). Don't move app/ away from assets/.
• Browser extensions / strict content blockers can interfere — try a clean profile to isolate.

"I ran a vault sync and nothing happened"

A sync that reports "already in sync" means there was genuinely nothing to do — both sides matched. That's success, not failure. Other reasons it may look like nothing happened:

• You changed files but they're not .md. Only Markdown files sync. Other file types are ignored.
• The change is inside a dot-folder. .obsidian, .trash, .git, and other dot-folders are skipped by design.
• Auto-sync already moved it. If auto-sync is on, the change may have synced quietly already; the next manual sync then shows "already in sync."
• You're on the wrong sync mechanism. Browser folder sync (⇄ Vault sync) is separate from the cloud org vault (Sign in) and the Obsidian plugin. Make sure you ran the one you meant.
• Permission expired. If the browser revoked folder access, sync errors instead of running — see Permission denied.

To verify it's working: make a small edit to a note in Obsidian, click ⇄ Sync now in Ledger, and watch for the summary ("1 pulled …"). Then edit in Ledger and sync again to confirm the push direction.

"Permission denied on the vault folder" / "Vault permission not granted — reconnect the folder"

The browser controls folder access for security, and it can ask again or revoke it.

• On return to the app: the browser re-asks permission for a previously connected folder. This is expected. Approve it and continue.
• If you denied the prompt: open the vault sync panel and click Change folder (or Connect Obsidian vault) and grant read & write this time — read-only isn't enough, because Ledger needs to push edits back.
• If the error persists: click Disconnect, then reconnect the folder fresh. Your files are untouched by disconnecting.
• Right browser? Folder sync only works in Chromium browsers (Chrome/Edge/Brave/Arc). On Firefox/Safari you'll see the "this browser can't open a folder" message — use the Import/Export fallback.

Sign-in failed (web app or plugin)

In the web app:

• Nothing happens when I click sign in: a pop-up/redirect blocker may be interfering, or the sign-in script was blocked. Allow the redirect, or try a clean browser profile.
• "Cloud tier is unavailable": the cloud module couldn't load — you may be offline, behind a network policy that blocks it, or running an environment where it isn't deployed. The local app keeps working regardless; retry when you have connectivity.
• Redirected but came back signed out: complete the full sign-in on the hosted page; if it loops, clear cookies for the sign-in domain and retry.

In the Obsidian plugin (Verify fails):

• "add your access token first": paste your token in Settings → Ledger → Access token, then Verify.
• A 401 / "not signed in" with a token present: the token may be wrong, expired, or revoked — generate a fresh one. If a brand-new token still 401s, your environment may not yet accept pasted personal access tokens on the API (a known platform dependency — see the plugin notes).
• Wrong API base: confirm Settings → Ledger → API base is https://api.dosanjhlabs.com (only change it for staging/self-hosted setups).

"My page/secret got flagged on save"

Ledger's save-time scanner warns when a page looks like it contains a pasted secret. Two cases:

• It really is a secret: good catch — don't store it. Remove the value and link a vault item instead. Ledger stores no secrets by design.
• False positive (e.g. the words "password:" or "api key:" appear in normal documentation, or you reference a key format): the warning lists what it matched. You can click OK / Save anyway to proceed — the scanner is intentionally cautious and is a guardrail, not a hard block. To avoid the warning entirely, reword so it doesn't look like password: value (e.g. describe the field without a literal : + value).

A published portal won't open / looks wrong

• Nothing downloaded: only Admin can publish. Switch the role picker to Admin, then click Publish ↗ on the space header. A browser download blocker can also stop the file — allow downloads from the app.
• "That space has no pages": the folder you tried to publish is empty. Publish a space that has pages.
• The HTML file won't open: it's a standalone .html — double-click to open in any browser. If your OS opens it as text, right-click → Open with → your browser.
• It's out of date: a portal is a point-in-time snapshot. Re-publish to share the latest version.
• No secrets in it? Correct — portals carry no secret material by design, even if your space references credentials (those are vault links).

Browser support & "a feature is missing"

If folder sync controls are missing, you're likely on Firefox/Safari — use the Import/Export fallback or the Obsidian plugin. If the Edit tab is missing, your role is read-only — switch to Admin or Editor.

Data loss & recovery

Local docs live in your browser's storage on this device. They can disappear if you clear browser data, use a different browser/profile, or open a private window. To protect against that:

• Best practice: keep a copy outside the browser — sync to a vault folder, sign in and sync to the org cloud, or periodically Export all to a Markdown bundle.
• Recover a previous version of a page: open it → History tab → Restore. Restores are non-destructive (the current version is snapshotted first).
• Recover a deleted page: if it's still in a connected vault folder or the org cloud, run a sync/pull to bring it back. If it only ever lived in the browser and you deleted it, it can't be recovered once gone — which is why a folder/cloud copy or an export matters.
• Switched devices: docs don't follow you automatically in the free tier. Export and import, or sign in and sync, to move them.

Resetting Ledger / starting fresh

To wipe the in-browser KB and re-seed the sample data:

1. Export first if you want to keep anything (Export all).
2. Clear Ledger's site data for this origin in your browser (clear localStorage/IndexedDB for the site, or use the browser's "clear site data" for that URL).
3. Reload the app — with no docs present, it re-seeds the sample KB on the next first run.

This also clears the connected vault handle and the saved AI key, so you'll reconnect/re-enter those.

AI errors

• "No AI key set" / "Add an AI key first": open AI, pick a provider, paste your key, Save key. See AI setup.
• "Blocked: the text may contain a secret or PII": the scrubber stopped the draft because your notes look like they hold a secret/PII. Remove it (link a vault item) and retry.
• Provider error (401/403): bad or unauthorized key — re-check it in the provider's dashboard. (429: you're rate-limited or out of credit with the provider.)
• "No text in provider response": the model returned nothing usable — try again, a different model (Model override), or a different provider.
• Reminder: the call goes directly to your provider from your browser, so errors come from them, not from DosanjhLabs. AI output is advisory — review before adopting.

Exporting & leaving (no lock-in)

Ledger's source of truth is plain Markdown, so leaving is trivial:

1. Click Export all to download the whole KB as a portable Markdown bundle (or Export .md per page).
2. Drop the files into an Obsidian vault, or commit them to a git repo — they're standard .md with frontmatter and [[wiki-links]] intact.
3. If you used a connected vault folder, your files are already on disk — nothing to export.

There's no proprietary database to escape. git clone / export is both your backup and your exit.

General FAQ

Do I need an account to use Ledger? No. The free, local-first tier works with no account and no network.

Does anything leave my machine if I don't sign in? No — signed out, Ledger makes zero network calls.

Can I store passwords in Ledger? No, by design. Link a password manager item from a credential page; a save-time scanner warns if you paste a secret. See Security & privacy.

Is it really compatible with Obsidian? Yes — same Markdown, YAML frontmatter, [[wiki-links]], folders, and tags. Import a vault, keep editing in Obsidian, export back out.

Why are Mermaid diagrams shown as code? The renderer is dependency-free and displays ```mermaid blocks as code rather than executing them into diagrams.

How many versions does history keep? Up to the last 30 saves per page, locally.

Where's the desktop app? The cross-platform "desktop" experience ships as the Obsidian community plugin — Obsidian is already the Mac/Windows/Linux/mobile host.

Is there a graph view? There's a navigable Links view (out-links + backlinks + a connectivity summary). A visual force-directed graph is on the roadmap.

Still stuck?

Re-check the topic page for the feature involved — it has the step-by-step details:

• Getting started · Features · Vault sync · Obsidian plugin · AI · Cloud tier · Security · How do I…?