Troubleshooting

The Installer Stops Early

• Confirm the host is macOS or Linux on AMD64 or ARM64.
• Run docker info and docker compose version.
• For local auth, run codex login status, then codex login when needed.
• For API-key auth, export the variable configured in local-stack.json.
• Check access to downloads.oblive.dev and Amazon ECR Public.
• Rerun the same installer command. Existing configuration is preserved.

The installer verifies the release checksum and rejects unsafe archive paths, links, corrupt downloads, unstable versions, and an unrelated file already occupying the CLI path.

The Stack Does Not Start

1. Run oblive doctor.
2. Run oblive config check.
3. Check configured host ports in oblive config edit.
4. Run oblive status.
5. Read logs for the first unhealthy dependency rather than the last service that failed.

If you are developing from source, use the equivalent bun run stack config, ps, and logs commands from the developer guide.

Codex Authentication Fails

For local mode:

oblive auth status
oblive auth login
oblive restart --no-open

Only auth.json is synchronized. An invalid host Codex configuration can also prevent the Codex CLI from reporting login status; correct that configuration with Codex before retrying.

For API-key mode, ensure the configured environment variable is exported in the shell that runs oblive start.

Migrations Fail

Confirm PostgreSQL is healthy, the configured credentials are valid, and the migration service can reach the Compose database. Do not reset data merely because a migration failed. Read migration logs first:

oblive logs migrate
oblive logs postgres

An Update Fails

oblive update preflights the new bundle before switching. If startup fails after migrations may have run, it leaves the new release installed and reports the retained previous files rather than automatically downgrading the database.

Check oblive status and service logs. Do not manually replace the installation with an older release; restore a compatible data backup when a rollback is required.

Chat Does Not Respond

Check backend and agent-chat logs. A pending response should be recoverable after a missed live signal, so avoid repeatedly submitting the same request while services restart.

A Task Does Not Run

Check whether it is due, dependency-ready, within attempt limits, unblocked, and free of conflicting active work. Inspect the latest attempt and Human Inbox before creating a replacement task.

Onboarding Cannot Continue

Confirm the organization and every selected department have at least one source. Check extension, size, filename length, UTF-8 encoding, and PDF text-layer requirements.

Context Looks Incomplete

Inspect sources and evidence status. Add or promote a current source rather than repeating an unsupported claim in chat. Run the context audit when broad health needs reevaluation.

An Integration Is Not Ready

• Confirm the credential or OAuth connection.
• Check selected tools or services.
• Check profile grants.
• Verify read-only annotations for MCP reads.
• Rotate or reconnect only after identifying the failing boundary.

Last Resort Reset

Use oblive reset --confirm only when losing all local stack state is acceptable. Reset is not a normal response to invalid configuration, an unavailable provider, or a blocked task.