Troubleshooting

Start with local status

ctxindex status --format json
ctxindex source list --format json
ctxindex oauth-app list --format json

Read the command's stable exit code and structured warning/error fields before retrying.

“Run init first”

Stateful commands require initialized local state. Run:

ctxindex init

init probes the secret backend and creates local config/data directories. It does not create an implicit Realm.

Provider authorization fails

• The bundled Google and Microsoft OAuth Apps are not verified. The maintainer is an individual and cannot get them verified at the moment; provider review can also take several weeks. See the provider notes.
• Microsoft should still work without verification, but an organizational tenant can require admin consent or block unverified Apps.
• Google can show an unverified-app warning, limit access to named test users, or block requested scopes.
• Confirm the OAuth App is listed and choose its exact Provider-scoped label when using BYOA.
• Check provider tenant and administrator policy. A work or university tenant can block an app even when another desktop mail app is allowed.
• Confirm the Provider's current requested scopes are permitted for that App and tenant.
• If managed authorization is unavailable for your identity or tenant, configure local BYOA instead of bypassing the provider warning.
• Do not remove local Grant or secret state blindly. Reauthorization updates the existing Grant in place.

Source is unavailable

The Source Adapter's Extension may be absent or invalid. Locally materialized Resource envelopes are preserved; provider operations remain unavailable until the Extension loads again.

ctxindex extension list --format json
ctxindex describe adapter <adapter-id> --format json

Search returns nothing

• Confirm the Source belongs to the Realm you filtered.
• Run sync --source <label> --format json for indexed Sources.
• Use --remote only when exactly one eligible remote-search Source is selected.
• Remove --local-only only when provider traffic is intentional.