Troubleshooting & FAQ

"Anthracite can't be opened" / "unidentified developer" / "is damaged"

The signed release build from the DMG should open normally. If you see Gatekeeper warnings, you may be running an unsigned local/dev build — see Gatekeeper (unsigned dev builds only).

Gatekeeper (unsigned dev builds only)

If you built Anthracite locally without signing, macOS may block the first open. Either right-click → Open and confirm, or strip the quarantine flag:

xattr -dr com.apple.quarantine /Applications/Anthracite.app

Full details are in Getting started. Release DMG users should not need this.

The backend won't start / "Can't reach API"

The desktop app shows a status dot in the top-right; "Can't reach API" or a "Backend offline" banner in Settings means the local backend isn't responding.

• Packaged app: quit Anthracite completely and relaunch. On first launch the backend is extracted and started automatically; a relaunch re-runs the health-gated startup. If it persists, check for a port conflict (below) and the logs (below).
• Running from source: make sure the stack is up with pnpm dev (or anthracite serve for just the API), then refresh. Your vault data is always safe on disk regardless.

Port conflicts

When run from source the backend uses port 5050 by default (macOS sometimes uses 5000 for AirPlay). The packaged app picks a free loopback port automatically, so conflicts are rare there.

• The dev launcher refuses to start if its port is already in use — free the port or run on another one. Set ANTHRACITE_CORE_PORT (the Vite proxy follows it) and, for a standalone API, pass -p to serve / set CORE_SERVICE_URL.
• To see what's actually bound, the real port for the running vault is shown in Settings → Developer (it's part of the Endpoint URL).

Ollama not detected

In Settings → Ingestion & OCR the local-model card tells you the exact state:

• "not running" — Ollama is installed but its app/server isn't up. Start the Ollama app, then click Re-check.
• "not installed" — click Download Ollama, install it, then Re-check.
• Installed + running but model missing — click Install <model> to pull the recommended model (a progress bar shows the download).

If it still isn't detected after starting Ollama, confirm Ollama is listening on its default local endpoint and re-check.

Apple Notes sync says it needs Full Disk Access

macOS protects the Notes database, so this one permission is required. Open System Settings → Privacy & Security → Full Disk Access (the card in Settings → Connections → Apple Notes links straight there), enable Anthracite, then retry the sync. If the error says the database is busy, quit the Apple Notes app and sync again.

Voice memos stay "pending" and never transcribe

Transcription needs a local Whisper CLI, which isn't bundled with the app. The Settings → Voice card shows which binary the selected engine expects (default: whisper-ctranslate2 for faster-whisper). Install it (e.g. pip install whisper-ctranslate2, or brew install whisper-cpp for the whisper.cpp engine) and process the source again. There is no cloud fallback — audio is transcribed on your Mac or not at all.

reMarkable page previews are blank or stale

Re-sync the notebook — page rendering is incremental, and a re-sync re-downloads and re-renders anything broken. If handwriting renders but the read text is poor, change the OCR Provider / Default OCR language in Settings → Ingestion & OCR and use Read again on the source (or Read page N again for a single page) in Review.

A capture API returns 401 Unauthorized

• Local ingest API: the Bearer token is missing or wrong. Copy a fresh one from Settings → Developer → Local ingest API. Remember each vault has its own token — if you switched vaults, re-paste it into your clipper/scripts.
• Webhook: the secret in the URL is wrong. Copy the full Webhook URL from Settings → Developer → Webhook ingest.

A capture API returns 400

• Local ingest: the JSON body must be an object with at least a non-empty title or text/html.
• Webhook: the body must contain some text (text, body, or content), or be a non-empty text/plain body.

See the working curl examples in Capturing content.

A remote webhook (Zapier, etc.) can't reach me

The backend binds loopback (127.0.0.1), so only senders on this Mac (e.g. Apple Shortcuts) reach it directly. Remote senders need a tunnel to your machine. An always-on hosted webhook is a planned Anthracite Cloud feature.

I edited ANTHRACITE.md — why didn't the wiki change?

Saving ANTHRACITE.md triggers a recompose (instant, free, no LLM) that rewrites the board/tasks only. The wiki (and page reading) is refreshed by processing again — use the Process now button on the banner the app shows after the change, or process the affected sources manually. See Core concepts.

Where do my files, state, and logs live?

• Your vault — the folder you chose (contains ANTHRACITE.md, .anthracite/, raw/, wiki/, tasks/). This is all your data; back it up.
• Per-vault state — <vault>/.anthracite/state.json (ingest token, webhook secret). Operational config is <vault>/.anthracite/config.json.
• Global registry — ~/.anthracite/state.json (known vaults + last opened).
• Packaged app support files — ~/Library/Application Support/Anthracite/ (the extracted backend, etc.).
• Logs — when run from source, logs print to the terminal running pnpm dev / anthracite serve. For the packaged app, run it from a terminal to see backend output, or check the macOS Console app.

How do I switch between vaults (e.g. Work vs Personal)?

Settings → Vault lists known vaults and lets you add/switch; switching prompts a guided backend restart. From the CLI (running from source only — the packaged app has no CLI): anthracite vault list / vault add <path> / vault use <path>. See Core concepts.

Why does Anthracite ask for Touch ID?

Because your vault holds your most private writing — journals, ideas, raw thoughts — and your connected-account tokens. The prompt keeps both safe from anyone else with access to your Mac. The check runs entirely inside macOS (Anthracite never sees your fingerprint), and in the alpha it's a soft gate — cancelling won't lock you out. Details in Getting started.

Is any of my data uploaded?

No. Anthracite is local-first: capture, processing, and storage all happen on your machine. If you choose a hosted LLM via your own API key, only the text you send to that provider for processing/answering leaves — running a local model (Ollama or MLX) keeps everything on-device.