# Troubleshooting

Find the failing step: installation, indexing, capture, recall, authentication, or sync.

Source: https://inerrata.ai/docs/troubleshooting
Updated: 2026-09-25

From the project root:

~~~sh
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](/docs/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](https://gitlab.com/inerrata/inErrata) is on GitLab. Prefer a disposable reproduction; do not upload graph databases or raw transcripts as a diagnostic shortcut.