Troubleshoot a self-hosted installation

Use this page when an install stops. For a single VM, read the Compose logs. For a cloud install, read the Fleet Manager log. Match the error text, then apply the fix.

docker compose logs app --tail=50
docker compose logs caddy --tail=50
docker compose --profile runners logs fleet-manager --tail=50

kubectl logs -n superplane deploy/fleet-manager-fleet-manager --tail=20

Symptom	Provider	Fix
Certificate stays pending	Single VM	The DNS A record must point at the VM. Ports 80 and 443 must reach Caddy. Run docker compose logs caddy --tail=50.
app is not healthy	Single VM	Run docker compose logs app --tail=80. superplane.env must set BLOB_STORAGE_PROVIDER=filesystem. Run ./install.sh again. It keeps the existing secrets.
No runner container starts	Single VM	On Set up runner fleets, select This VM and run the command from that page. Then run docker compose --profile runners ps.
runner version does not match	Single VM	runnerVersion in fleet-manager.yaml must equal the tag of ghcr.io/superplanehq/runner. Run ./install.sh, then run the command on Start runners on this VM again.
SkuNotAvailable or NotAvailableForSubscription	Azure	Change the region or runner_zones. See the region table in the install guide.
QuotaExceeded	Azure	Request quota for DDSv4 or Dpdsv6, or lower maximum capacity. A new subscription often has 4 regional vCPUs, which fits one node and one runner.
On-Demand vCPU limit reached	AWS	Request more Standard vCPU quota (quota code L-1216C47A), or lower maximum capacity.
failed to load assume role	AWS	The profile assumes a role from an aws login source profile. Export the CLI credentials, run unset AWS_PROFILE, then run plan again. See the AWS sign-in step.
arm64 runner fails Trusted Launch	Azure	Set vmSize to Standard_D2pds_v6. Do not use a v5 size. Run Helm again.
Values file contains <AZURE_ZONE>	Azure	Set zones to terraform output -raw runner_zones, then run Helm again.
ParameterOutOfRange: The value of the 'Version' should be in: []	Azure	Set create_postgresql_flexible_server = false and apply again.
AMI not found, or the wizard disables a fleet	AWS	Stay in us-east-1. Run the image command in the install guide and set both AMI IDs to the newest match. Apply again and reload the wizard.
Runner image not found	Azure	Use eastus or westus3 for both architectures.
Pods stay Pending	Google Cloud	Set machine_type to e2-standard-2 or larger and apply again. That change replaces the cluster.
The page loads, then scripts fail	Google Cloud	Clear superplane_image_tag so the chart selects its image. A plain commit SHA is blocked on your domain. Apply again and hard-refresh.
ZONE_RESOURCE_POOL_EXHAUSTED	Google Cloud	Add zones in runner_zones and apply again.
Certificate stays pending	AWS, Azure, Google Cloud	The DNS name must be the host in domain_name. On AWS, dig +short your_domain CNAME @8.8.8.8 must print the load balancer hostname. On Azure and Google Cloud, dig +short your_domain @8.8.8.8 must print the address.
No runner machine appears	AWS, Azure	Run helm list -n superplane. Raise maxCapacity when every machine is busy.
fleet not found (404) once in the log	AWS, Azure, Google Cloud	Ignore that line when later lines show reconciliation.
terraform destroy stops on the load balancer	AWS	Follow the AWS installer README. Do not delete the Terraform state.

A first task with warm capacity 0 waits while the machine boots. That wait is the cold start, not a failed install.