Troubleshooting

From the project root:

errata --version
errata status
errata privacy

Local capture, cloud authentication, and uploads are separate checks. Verify the one you need before changing another.

Init requires login

In a non-interactive shell, plain errata init without credentials exits with a login hint. It may already have written workspace and hook files.

For a local trial, rerun errata init --no-login. For hosted access, complete errata login interactively. --no-login does not reset credentials or consent.

Daemon or graph missing

Local MCP normally starts the daemon when the client connects. init and hooks alone do not. If status says it is absent, run errata start, then errata status. Check the workspace path and daemon state. Indexing takes time; search for a known function afterward.

If needed, run errata reindex --no-embed. The default hook port is 7891. If you intentionally run the foreground daemon on another port, reinstall hooks with --port <number>.

Tools appear but nothing is captured

MCP connectivity verifies reads, not capture. Cursor's installer configures MCP only.

For a capture-capable integration:

1. Re-run errata install-hooks <harness> from the project root.
2. Restart the agent session.
3. Check that it reads live context and emits a real problem tag in its own prose.
4. Let its next hook or turn boundary occur.
5. Inspect errata g problems.

Hook and transcript formats vary. The released 2.0.5 Codex installer uses tool-triggered capture; its output explains that a final turn without a tool call may wait for daemon replay. Newer builds use newer wiring. Check your installed version rather than assuming identical timing across clients.

Search is empty or selects the wrong seed

Check a known file or symbol first. If code is present but the problem is absent, debug capture. If the problem exists, use its exact ID with errata burst.

.errata/context.md is a budgeted selection, not an inventory. An omitted problem can still be queried. New workspaces may have sparse relationships and prior knowledge.

Embeddings fall back to hash vectors

In the Windows onboarding check of npm latest 2.0.5, search, capture, and recall worked, but burst reported an unavailable embedding model and fell back to hash-v1 vectors. Semantic ranking runs at reduced fidelity in that mode.

Record the package version and full warning when reporting this. Do not treat reduced-fidelity ranking as proof that setup failed or that the top result is reliable.

Doctor fails while local queries work

doctor checks cloud installation and credential health. Without a login or named installation profile it can exit nonzero while the local graph works.

Use status and a local query for local readiness. For cloud access, read individual doctor --json checks, complete Console setup, and verify whoami. A parser-version warning is a compatibility lead, not proof of broken capture.

Hosted requests fail

Check the endpoint, environment, credential, and tool schema. Use Console Connect for current setup. A successful local query does not establish hosted access.

Authentication failures need a valid identity for that deployment. Forbidden writes may involve scope or consent. Follow the specific error; do not enable every consent channel to troubleshoot a read.

Sync uploads nothing

Inspect errata sync now results:

• consent-off means the lane was intentionally skipped.
• No queued knowledge may mean nothing needs sending.
• Failed or rejected uploads need their specific error inspected.
• Local capture does not establish a cloud project or contribution target.

Check privacy and whoami before changing upload settings. See Team workspaces.

Report a reproducible issue

Include OS, Node version, errata --version, agent version, command, expected result, and actual result. Add relevant diagnostic checks with credentials, personal paths, and identity details removed.

The source repository is on GitLab. Prefer a disposable reproduction; do not upload graph databases or raw transcripts as a diagnostic shortcut.