Diagnose a deployment

Start with the current project and original operation:

ohmyhost project context --project "$PROJECT_ID" --json
ohmyhost operation get "$OPERATION_ID" --json
ohmyhost logs "$OPERATION_ID" --follow --json

Read the stable error code, suggested action and any retry interval. Keep source-admission failures, build failures and pending DNS/mail separate. For a connected chat, verify the intended account and project grant through the connection flow. Read the saved source and keep its original upload or deployment operation after uncertainty. If another chat changed the source, reconcile the current files before saving a new version. Private credentials use the portal input flow; a missing secret is not a reason to paste it into chat.

Result	Next action
Source blocker or conversion requirement	Inspect the exact source file/capability, fix it, save a managed version or push the GitHub commit, then plan that exact commit.
`progress.phase: waiting_for_mail`	Read `mail_status` (same as `mail_domain_status`) with the Prod environment ID; apply its required records.
`reconciliation.state: required`	Review the operation and perform one confirmed reconciliation.
`reconciliation.state: pending`	Wait and inspect the existing operation; do not submit another attempt.
`error.code: build_failed`	`operation get` names the failed deployment as `deployment_id`. Read its diagnostics: `ohmyhost deployment logs --project "$PROJECT_ID" --deployment "$DEPLOYMENT_ID" --follow --json` or MCP `deployment_logs`. The `BUILD_FAILED` item carries `excerpt`, the sanitized tail of your own install/build output (newest lines last; `excerpt_truncated` means earlier output was omitted). An ending ohmyho.st packaging: line names an output size/file limit. Fix that cause, save a managed version or push the GitHub commit, then plan that exact commit. Without an excerpt,the build may have printed nothing,hit the eight-minute deadline or failed inside the platform; plan the same commit once more,then report both IDs if it repeats.
`error.code: runtime_candidate_failed`	The new deployment failed its health check. In the same deployment logs, the `HEALTH_CHECK_FAILED` item names the `route`, the `status_code` it answered and, for a project owner, an `excerpt` of the response. The check is a cookieless `GET` that follows no redirect, so a redirect fails too. Each probe has five seconds and follows no redirect; an ordinary login redirect fails. After promotion/rollback,first fix the target environment secret if that is the cause and plan again. For source errors, save the corrected managed version or push the GitHub commit, then plan that exact commit. If the probe throws or exceeds the timeout repeatedly,a diagnostic can be absent and the original operation may require reconciliation. A previous deployment keeps serving when the new candidate fails.
`error.code: runtime_candidate_rejected`	The runtime refused the built Worker script. Check the default export and imports of `src/ohmyhost/worker.ts`, then plan the new commit.
`error.code: storage_jurisdiction_conflict`	Match storage.jurisdiction to the immutable us/eu project region from project status, save a managed version or push the GitHub commit, then plan it; the project cannot move regions.
`error.code: database_migration_failed`	Read DATABASE_MIGRATION_FAILED’s file/catalog reason; none of the new files applied. Preserve applied files and use later timestamps. Follow expand-only admission; never reset the database.
CLI 0.1.24 init/plan `managed_auth_mail_required`	Upgrade to CLI 0.1.25 or later. Older clients incorrectly required managed mail for Better Auth. Preserve your auth and chosen sender; only calls through ohmyho.st Mail need its capability, Paid access and verified sender.
App `402 Project execution paused`	Resolve Stop budget,expired seven-day credit grace,or custom hostname lacking Paid/flag eligibility. Serving resumes within about five minutes; redeploying cannot fund it.
App `429 Runtime limit exceeded`	Reduce work to fit50msCPU/ten subrequests; use small batches. This is not a request rate limit.
App `502 Upstream unavailable`	The app threw or failed to run; read that deployment’s diagnostics.
App `503 Service unavailable` or `Credit check unavailable`	Address/credit/Dev check unavailable,or Dev passed about1,200requests/minute. Wait/retry; load-test Prod.
Non-GET/HEAD `403 Forbidden`	Verify Origin/cookies and the committed browser/CORS declarations.
Server `403 Egress denied` or `502 Egress upstream unavailable`	For an external customer destination, add its exact HTTPS origin to runtime.egress.allow and deploy the corrected source; redirects require the final URL. 304 is preserved. Platform mail/storage gateway origins are allowed automatically; diagnose their errors below.
Cron absent or failed	Read function_runs_list or function runs with the actual environment ULID; state,attempt,status_code describe the outcome. Observe runs.
`response_contract_invalid`,or old MCP `client_request_failed` with working login	Compare installed CLI/MCP with current release,upgrade both/reload MCP,then replay the original request/key. If current,report the request ID.
HTTP 429	Respect `Retry-After`; do not fan out retries.

Mail and file gateway errors

Use global fetch to the injected gateway URL with the environment’s runtime key. Gateway and signed R2 origins are allowed by the platform; do not add them to runtime.egress.allow or replace them with customer gateway bindings. The database retains its own OHMYHOST_DATABASE binding. Run the current CLI’s ohmyhost init --dry-run --json to find legacy gateway references (gateway_binding_unsupported) or a declared storage capability without a client (storage_client_missing). See Files and Email for the runtime values.

403 gateway_not_enabled: enable the capability in ohmyhost.yaml and redeploy. This request is not retryable unchanged.
403 gateway_route_denied: use the current runtime client’s supported route, method and query. It is final for that request and does not require a broader egress allow-list.
429 gateway_rate_limited: wait, then retry with the original idempotency keys. Mail and file calls share the approximate project gateway limit of 1,200 calls a minute per Cloudflare location.
503 gateway_unavailable: retry after a delay with the same message/object and key. With status null, the supplied fetch threw before a response was received.
gateway_timeout: the configured wait expired; a durable effect may still have occurred. Observe or retry the original operation with its existing key.
gateway_response_invalid: the response was malformed or non-JSON. The error retains any received HTTP status and excludes upstream text. Report a persistent failure through feedback.

A missing URL/key produces non-retryable gateway_configuration_invalid, naming the option. Resolve private configuration from the hosted request context. Keep the health route independent of mail/storage: the deploy-time probe runs without the egress policy. Do not include runtime keys, signed URLs or raw upstream responses in feedback.

Reconcile only when requested

ohmyhost operation reconcile "$OPERATION_ID" --idempotency-key "$RECONCILE_KEY" --yes --json

Use this when the operation reports reconciliation is required and no attempt is pending. Retain the same request key across uncertainty. A completed reconciliation attempt does not itself mean the original deployment succeeded.

Read diagnostic pages

Deployment diagnostics/logs are retained seven days. CLI deployment logs reads one page of at most100 items despite —follow; MCP deployment_logs takes cursor. Pass next_cursor as cursor for older records. DEPLOYMENT_FAILED carries no detail: follow the failed operation’s suggested_action. Operation logs is separate: CLI logs —follow has bounded reconnects/Last-Event-ID; operation_stream_ended means the original still runs,so poll operation get about every sixty seconds. No work was cancelled.

Error codes

Act on code,retryable andsuggested_action. Only CLI errors returned by the API add docs_url; local CLI/MCP and terminal operation failures use their own guidance.

Code	HTTP	Retry
`api_key_creation_uncertain`	503	Yes
`api_key_permissions_unavailable`	503	No
`billing_purchase_conflict`	409	No
`billing_recharge_conflict`	409	No
`cloudflare_authorization_closed`	409	No
`cloudflare_zone_not_bound`	409	No
`compute_change_conflict`	409	No
`compute_change_pending`	409	No
`compute_paid_required`	403	No
`compute_performance_paid_required`	403	No
`compute_performance_unavailable`	503	No
`compute_storage_shrink_requires_migration`	409	No
`confirmation_expired`	409	No
`confirmation_invalid`	409	No
`data_change_blocked`	409	Yes
`data_change_in_progress`	409	Yes
`data_change_not_applicable`	409	No
`database_access_limit`	409	No
`database_write_pending`	409	No
`deployment_plan_expired`	409	No
`deployment_plan_incompatible`	409	No
`domain_dns_conflict`	409	No
`domain_hostname_taken`	409	No
`environment_secret_mutation_blocked`	409	Yes
`etag_mismatch`	409	No
`forbidden`	403	No
`framework_conversion_required`	409	No
`github_connection_required`	409	No
`github_connection_revoked`	409	No
`idempotency_key_reused`	409	No
`insufficient_organization_credits`	402	No
`interactive_login_required`	403	No
`invalid_request`	400	No
`mail_capacity_unavailable`	503	Yes
`mail_domain_conflict`	409	No
`mail_domain_required`	409	No
`migration_filename_noncanonical`	409	No
`organization_required`	409	No
`paid_plan_required`	402	No
`payload_too_large`	413	No
`powered_by_flag_required`	409	No
`production_deployment_required`	409	No
`project_budget_exceeded`	402	No
`project_domain_delete_required`	409	No
`project_export_not_ready`	409	No
`project_handle_invalid`	409	No
`project_handle_taken`	409	No
`project_handle_unavailable`	503	Yes
`project_handle_unchanged`	409	No
`project_identity_unavailable`	503	Yes
`project_notes_conflict`	409	No
`project_rename_blocked`	409	Yes
`promotion_invalid_target`	409	No
`promotion_source_stale`	409	No
`promotion_target_stale`	409	No
`rate_limited`	429	Yes
`reconciliation_exhausted`	409	No
`repository_configuration_missing`	409	No
`repository_not_installed`	403	No
`resource_not_found`	404	No
`rollback_target_data_changed`	409	No
`service_unavailable`	503	Yes
`shared_data_requires_promotion`	409	No
`source_commit_conflict`	409	No
`source_commit_not_found`	409	No
`source_generation_conflict`	409	No
`source_scope_unavailable`	404	No
`source_snapshot_invalid`	409	No
`source_snapshot_too_large`	413	No
`source_upload_conflict`	409	No
`source_upload_expired`	409	No
`storage_jurisdiction_conflict`	409	No
`unauthenticated`	401	No
`workers_runtime_incompatible`	409	No

Report a platform issue

If an error lacks a useful cause or the documented operation cannot continue, submit feedback with the project/operation IDs, expected behavior and a short redacted reproduction. Do not paste tokens, secret values, raw environment files or customer records. A provider observation failure means unavailable, not ready or zero usage. Keep customer source changes separate from a provider-capacity issue.

Start

Deploy

Operate

Agent reference

Legal

Diagnose a deployment

Mail and file gateway errors

Reconcile only when requested

Read diagnostic pages

Error codes

Report a platform issue

​Mail and file gateway errors

​Reconcile only when requested

​Read diagnostic pages

​Error codes

​Report a platform issue

Mail and file gateway errors

Reconcile only when requested

Read diagnostic pages

Error codes

Report a platform issue