Home Docs Architecture Production install Docker Compose deployment Configuration reference Connecting an AWS account Secret references OpenTofu runner and state Security hardening Upgrades and migrations Backups and recovery Observability Troubleshooting

Troubleshooting

Fixes for common OrkStage problems, from startup configuration errors and busy ports to MiniStack, OpenTofu runners, state buckets, permissions and webhooks.

Start with the correlation id. Every API error and every deployment carries one. Search the API and worker logs for it.

Common problems

Edit on GitHub

Observability

Follow an OrkStage installation through JSON logs with correlation ids, health endpoints, deployment events and the audit log. Metrics and tracing are planned.

Troubleshooting

Common problemsCopy Anchor Link

The API or worker exits at startup with "Invalid configuration"

docker compose fails with "port is already allocated"

MiniStack does not start, or RDS and ECS containers never appear

Target validation reports the state bucket as not accessible

Deployment fails in the targets phase with AUTHORIZATION_ERROR

Resources fail with "Cannot connect to the Docker daemon", or runners hang

Deploying returns "409 INSTANCE_BUSY"

Verification says "Resource no longer exists at the provider"

Webhook creation fails with UNSAFE_WEBHOOK_URL

Import upload returns 501 SCANNER_UNAVAILABLE

The console shows "The console could not load your session"

On this page

Common problems