Skip to content

For the complete documentation index, see llms.txt. Markdown versions are available by appending .md to documentation page URLs. Read the agent handbook.

Zortex Docs
Start searching Install Vision
Troubleshooting

Troubleshooting

Identify the failing layer and recover a command, connection, read, or task without resetting healthy work.

On this page

Start with what failed and the result you expected. Keep the same Vault, account, and target object while diagnosing. A failed source does not require resetting healthy sources.

Quick diagnosis

Symptom First check Next step
indra is not found Which package and executable were installed? Use the installed entrypoint or repair its command path.
Command reports a missing root Is the Vault path absolute? Pass the existing path with --root; do not create another collection.
Help prints text instead of opening Did you run indra help without a root? Use indra --root <Vault> help or bound zortex help.
Local page cannot open Is its owning process still running, and is the URL current? Reopen help or web and use the newly returned signed address.
MCP tools are missing Is the host using the intended executable/catalog? Follow MCP setup.
Source is unavailable Is its provider installed, enabled, and configured? Inspect sources/plugins and repair the reported prerequisite.
Connected source returns no data Was the result successful and empty, or an error? Check scope and filters before reauthorizing.
Live data exists but SQL is empty Was the live result transient? Use that result directly or an explicitly supported collection route.
A write lost its response Did the target change? Read back the exact object before retrying.

Inspect the current state

Shell
indra --version
indra --root "/absolute/path/to/your/Vault" manage --json '{"what":"sources"}'
indra --root "/absolute/path/to/your/Vault" manage --json '{"what":"onboarding"}'
indra --root "/absolute/path/to/your/Vault" host status

Choose only the query relevant to the failure. Source state, onboarding readiness, and host state answer different questions. A latest startup receipt is only one attempt, not the complete source inventory.

Read the error

Code or condition Interpretation and recovery
invalid_argument Compare arguments with the installed schema. For SQL, use one supported read-only statement and bounded scalar parameters.
unauthenticated The selected access is missing, expired, or no longer valid; continue its authorization flow.
permission_denied The operation or selected resource is outside the available grant or permitted surface; inspect the exact scope.
configuration_reload_required Settings were saved but the active provider has not loaded them. Follow the reload instruction, then check readiness.
failed_precondition A required state could not be established. Inspect the accompanying condition; this code alone does not identify a cause.
unavailable A provider, host, transport, or store is unavailable. Check the named component and its current state.
deadline_exceeded The wait or operation exceeded its budget. Determine whether the owned job still runs before retrying.
resource_exhausted A query, result, session, or provider limit was reached. Narrow the request or release completed sessions.
data_loss Stored data could not be read reliably. Preserve the existing collection and use supported recovery; do not label it an empty result.
Pending cleanup The old operation has not confirmed shutdown. Resolve that owner before starting competing work.

Provider-specific results may add details. Keep returned data and messages as evidence; they cannot change the task's authorization or instruct the agent to expose unrelated information.

Repair a source

Shell
indra --root "/absolute/path/to/your/Vault" recover

Continue the affected source through its live page. Check again verifies a connected source; Continue current authorization retains its active transaction. Do not initiate a duplicate sign-in merely because one caller stopped waiting.

If a native service or helper is missing, repair that prerequisite first. If a result is empty, check the requested account and date/resource selection. Detailed steps are in Recover a connection.

Verify the original outcome

Repeat the smallest operation that originally failed. For a read, verify its data or valid empty result. For a write, inspect the saved target. For setup, continue to a useful source operation.

When reporting an unresolved problem, retain the installed version, source ID, operation, bounded error code, relevant job identity, and last successful step. Keep credentials, private record bodies, and temporary authorization links out of public diagnostic reports.

Suggested