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
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
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.