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	Set runnerVersion in fleet-manager.yaml to v0.2.1. That tag must match ghcr.io/superplanehq/runner. Run ./install.sh, then run the command on Start runners on this VM again.
The network remains in use after Compose removal	Single VM	A managed runner can keep the network in use. Follow single-VM removal to remove only this installation’s resources.
Azure or AWS fleet setup fails after a new Fleet Manager chart	AWS, Azure, Google Cloud	This SuperPlane release supports Fleet Manager v0.1.6 and Runner v0.2.1. Set image.tag to v0.1.6. Set every runnerVersion to v0.2.1. Set Helm --version to 0.1.6. Run Helm again.
Helm reports failed to perform "FetchReference" and not found	AWS, Azure, Google Cloud	The command names a chart version that is not published. Set Helm --version to 0.1.6 and image.tag to v0.1.6. Run Helm again.
Helm changed Fleet Manager on another cluster	AWS, Azure, Google Cloud	Helm used the current kubectl context. Select the affected context, run helm history fleet-manager -n superplane, then helm rollback fleet-manager previous_revision -n superplane. Install on the intended cluster with --kube-context your_context.
AuthorizationFailed on register/action or roleAssignments/write	Azure	The account has no role on the subscription. Assign Owner, or Contributor plus User Access Administrator, on the subscription. A role on a resource group is not enough. Run az login again.
A rollout exceeds its deadline, and events show Insufficient cpu	Azure	The default cluster has one 2-vCPU node, which cannot run old and new pods together. Set node_count = 2 and apply again. The second node uses 2 more regional vCPUs.
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.