Deployment Failures

When a deployment fails, the environment moves to the 'failed' status. Here's how to diagnose the cause and recover.

Reading the error log

Go to the request detail page. Click View Logs. The log shows every OpenTofu step with timestamps. Failed steps appear in red with the error message.

Common patterns to look for in the log:

Error 403: The caller does not have permission

Cause: Service account is missing a required IAM role

Fix: Add the missing role in GCP Console → IAM. Required roles: Compute Admin, DNS Administrator, Storage Admin, Cloud Run Admin.

Error creating Network: googleapi: Error 409: already exists

Cause: A VPC from a previous failed deployment was not cleaned up

Fix: Go to GCP Console → VPC Networks and delete the network named aithroyz-<env-name>-vpc. Then retry the deployment.

Quota 'CPUS' exceeded

Cause: GCP project has insufficient CPU quota in the selected region

Fix: Request a quota increase in GCP Console → IAM & Admin → Quotas. Filter for 'CPUs' in your region. Changes take a few minutes.

Error: Error waiting for instance to create

Cause: VM creation timed out — usually due to a startup script error

Fix: Check the VM's serial console output in GCP Console for startup script errors. Use the Retry button to re-attempt.

Health check timeout after 15 minutes

Cause: One or more tools failed to start within the health check window

Fix: Check Portainer (https://portainer.<env>.ops.aithroyz.com) to see which container is unhealthy. View its logs for startup errors.

✓

The Retrybutton re-runs OpenTofu from the current state — resources that were already created are preserved. You don't need to destroy and start over unless the VPC/network is in a broken state.

Lifecycle PhasesRead article →DNS & ConnectivityRead article →Tool Health ChecksRead article →