Troubleshooting

Start by asking your agent for a health check:

Run Bahama’s diagnostics for this project. Explain what is healthy, what is
blocked, and the safest next action. Do not change infrastructure yet.

The agent uses:

bahama doctor --json
bahama status --json

Doctor checks the local runtime, manifest, provider tools, and sessions. Status checks locked resources against live provider state. Neither command repairs or deploys anything.

A provider tool is missing

installation_required includes the exact provider tool and install command. The agent should show you that command and ask before installing it globally.

Install only tools required by providers in this project, then retry the command that was blocked. A newer untested provider-CLI version may produce a warning while still proceeding.

Authentication is required

auth_required means the selected provider session is missing, expired, or no longer matches the planned account. The agent runs:

bahama auth login <provider>

You complete the provider’s consent flow. Do not paste a token into chat or bahama.yaml. After login, the agent verifies the session and retries the original command.

Bahama needs an account decision

decision_required often means the provider login can access several valid teams or organizations. The result includes the real choices and an exact writeBack path.

The agent should present every option, let you choose, write the selector to that path in bahama.yaml, and create a fresh plan. It should never rely on the provider CLI’s last-used account.

A plan is stale

Apply rejects a plan when its validated manifest, lock, migrations, account, or protected provider configuration no longer matches.

Do not edit or force the saved plan. Ask the agent to run bahama plan again and review the replacement. Approval from the old plan does not carry over.

Another operation is running

Bahama allows one mutating operation per project. Wait for the active process to finish. A lock left by a dead process is reclaimed automatically on the next operation; do not delete .bahama/op.lock while another Bahama process may still be running.

Apply stopped partway through

Read the failed step and recovery message first. Fix the reported source or provider problem without changing unrelated intent.

If the plan is still valid, the agent can rerun its exact apply command. Bahama rechecks completed postconditions and resumes at the first unfinished step. If the result says to re-plan—or any protected input changed—create a new plan.

A deployed application is not healthy

Bahama reports the operation as failed until the planned live check passes, even if publication itself completed.

Use the reported stage to narrow the problem:

• source or archive validation;
• dependency installation;
• application build;
• provider publication or readiness; or
• live URL verification.

Fix the application or configuration, then deploy again through Bahama. Do not mark the old operation successful or publish around the failed check.

A remote resource is missing

Keep bahama.lock and re-plan. The lock preserves healthy resource identities, so Bahama can replace one missing project without replacing the rest of the stack.

Do not detach everything to repair one resource. Without the lock, a provider may only be able to rediscover exact-name matches; renamed or generated resources can become orphaned from Bahama.

The repository identity changed

The lock is tied to its repository so a copied template cannot silently deploy over the original project.

• For an intentional new fork or template copy, review the consequences and run bahama detach --approved to resolve a fresh stack.
• If the same project merely moved or changed remotes, preserve the lock. The current CLI can report the reconnect choice but does not complete that repair automatically.

Status reports drift

Each resource reports ready, not_ready, unhealthy, or unknown. Material drift returns decision_required and blocks mutation until you decide what the project should become.

Use the provider’s reason. Do not infer that exists: true means a resource is healthy, and do not edit the lock to hide a mismatch.

Deploy keeps asking for approval

Common causes include a first deployment, pending migration, new or rewired binding, changed provider configuration, missing local deployment baseline, or a live framework mismatch.

This is the classifier protecting the project. Review the plan and let the agent apply it after approval. A later code-only deployment can return to the routine path.

A secret appeared in output

Stop sharing the output and rotate the value at its provider. Report the redaction defect with the secret removed. Do not preserve the raw value in an issue, screenshot, fixture, or chat transcript.