Deploy troubleshooting

The deployment stopped in “Needs config”

Before planning, Deploy analyzes your repo and records a readiness report. When that report contains a blocker — no container build target, an ambiguous container port, configuration it couldn’t infer — the deployment parks in needs_config rather than planning against a guess.

Open the deployment to read the report. Common fixes:

Add a container build target. The web-service module needs your repo to be containerized. Add a Dockerfile that builds and runs your app, commit it, and redeploy.
Set the container port. If your app listens on something other than the default 8080, say so — the analyzer flags a port it can’t determine rather than guessing wrong and shipping a service that never passes health checks.
Supply the missing app variable. If your app needs configuration to start, add it as a workspace app variable and redeploy.
Override the report. If you know the blocker doesn’t apply, override it and Deploy proceeds to the plan. Overriding skips the advice, not the approval — you still review and approve the plan.

“A deployment is already running” (`deployment_busy`)

You sent a message to a deployment (for example “add a database”) while a plan or apply was still in flight. Wait for the current run to reach awaiting_apply, live, or failed, then send it again.

“Add a database” didn’t change anything

It probably did — staging a change is not applying it. The request appends the module and the wiring, then puts the deployment back at the plan and stops. Nothing is provisioned until you approve, so the running deployment is deliberately untouched until then. Review the new plan and approve it.

If you asked on the chat home page, name the deployment in your request; without one the agent doesn’t know which deployment to change. And if a plan or apply was already in flight, the request is refused as busy — wait for the current run to settle and ask again.

“Connect your AWS account first”

Deploy reads all cloud credentials from Connect. If your workspace doesn’t have an authorized AWS connection, the deployment fails immediately before any plan is attempted.

Fix: open connect.destesi.io and authorize your AWS credentials for the active workspace. Once the connection is active, re-submit your Deploy prompt.

“Connect your GitHub repo first”

The agent fetches your repo’s contents to inspect it. If the repo isn’t connected in Connect, the agent can’t access it.

Fix: open connect.destesi.io and authorize the GitHub repo (or the GitHub App installation that covers it). Then re-submit your Deploy prompt.

Plan or apply failed — reading the log

When a deployment moves to failed, the streamed log in the Deploy UI contains the full Terraform output including the error. Common causes:

AWS permission error — the credentials authorized in Connect don’t have the required IAM permissions (e.g. ecr:CreateRepository, ecs:CreateService, elasticloadbalancing:CreateLoadBalancer, and rds:CreateDBInstance if your stack includes a database). Attach the necessary IAM policies to the AWS user or role in your AWS account, then redeploy.
Region not enabled — some AWS regions require opt-in activation in your AWS account. If the region in your prompt isn’t activated, Terraform will error. Enable it in the AWS console and redeploy.
Resource name conflict — a resource with the same name already exists in your AWS account outside of this deployment’s Terraform state. Rename it manually in AWS, or choose a different deployment name.
Image build failed — the failure happened in building_image, before Terraform ran at all. The log shows your container build output; the fix is in your repo’s container definition, not in your AWS account.

After fixing the underlying issue, click Redeploy. That re-analyzes the current repo, re-composes the stack, re-plans, and parks at the approval gate — it never applies on its own. A destroyed deployment cannot be redeployed; create a new one instead.

A deployment is stuck in “Planning”, “Building image”, or “Applying”

If a deployment has been in planning, building_image, or applying for more than a few minutes without any log output:

Check your AWS account for any service-limit errors or CloudFormation/Terraform locks in the target region.
If the log stream in the Deploy UI is blank, try refreshing the page — a network blip can disconnect the stream without affecting the underlying operation.
If the deployment is truly wedged (no AWS resources created, log is empty), use Destroy to clean up and start fresh with a new deployment.

A deployment is “Live” but the service isn’t reachable

The live URL is the Application Load Balancer endpoint. Common causes if it isn’t responding:

Health checks failing — the ALB target group performs health checks against your container. If your app doesn’t respond with a 2xx on the health-check path (default /), the ALB marks targets unhealthy and returns 503. Check the CloudWatch logs for your container (visible in the AWS console) to see what the app is doing on startup.
Container exiting on startup — check the CloudWatch log group (named after your deployment) for panic, missing env vars, or port binding errors. If it’s a missing variable, add it as a workspace app variable and redeploy.
Wrong port — the load balancer accepts traffic on port 80 and forwards it to your container’s port, which defaults to 8080. Make sure your app actually listens on the port the deployment was configured with, and that your container definition exposes it.

Destroy doesn’t clean everything up

terraform destroy removes every resource in Terraform’s state for that deployment. If you see leftover resources in your AWS account:

They may have been created manually outside of Deploy and are not in Terraform state — Terraform won’t touch them.
If you believe a resource should have been deleted but wasn’t, check the destroy log for errors. Fix any permission issues (see “Plan or apply failed” above) and re-run Destroy.

Deploy uses Destesi’s shared single sign-on. If you’re redirected to the sign-in screen, your session has expired. Sign back in at account.destesi.io — your session will carry back into Deploy automatically.