Troubleshooting

Solutions for common Cloud Deploy issues: infrastructure, deployments, custom domains, connections, and delete site.

Connection Requirements

Cloud Deploy Says I Need AWS and GitHub

You see a message that you need an AWS connection and a GitHub connection to use Cloud Deploy.

Cause: Cloud Deploy requires at least one active AWS connection and one active GitHub connection in your organization.

Solution:

1. Go to Connections in the sidebar
2. AWS - Add and validate an AWS connection. Ensure it shows Active.
3. GitHub - Connect GitHub from the Connections hub and ensure at least one installation is active
4. Return to Cloud Deploy and try creating a site again

No Repositories in the New Site Wizard

In Step 1 of the New Site wizard, the GitHub repository dropdown is empty.

Possible causes:

• GitHub connection is not active or has no installations
• The GitHub App has no access to the repositories you expect

Solution:

1. Go to Connections → GitHub and confirm the connection is Active
2. Check that the GitHub App is installed on the account or organization that owns the repo
3. Refresh the New Site page and try Step 1 again

Infrastructure Issues

Site Stuck on "Provisioning"

The site status stays Provisioning for a long time.

Possible causes:

• AWS permissions insufficient (e.g. S3, CloudFront, IAM)
• AWS rate limits or temporary errors
• Infrastructure creation is still in progress (can take several minutes)

Solution:

1. Wait - Provisioning can take 5–15 minutes. Refresh the site page.
2. Check infrastructure - On the site page, use Check to see the current plan/state and any errors.
3. Retry - If status is Failed, click Retry to restart provisioning.
4. AWS permissions - Verify your AWS connection has the required permissions (S3, CloudFront, IAM).

Infrastructure Status: Failed

The site shows Failed and infrastructure did not become ready.

Solution:

1. On the site page, click Check to open the infrastructure plan/state and read any error message
2. Click Retry to run provisioning again
3. If it still fails, use Refresh / Reconcile from the Check modal
4. Verify AWS connection permissions. See AWS Connections - Troubleshooting

Deployment Issues

Deployment Failed

A deployment finished with status Failed.

Solution:

1. Open the progress page for that deployment
2. Read the logs to find the error

Common causes:

• Build command or output directory wrong - Fix in Settings → Build and redeploy
• Missing env var - Add the variable in Settings → Environment and redeploy
• Node version mismatch - Change Node version in Settings → Build and redeploy
• Install or build script failure - Fix the script or build stages and redeploy

3. Click Redeploy to run the same deployment again after fixing the issue

Deployment Stuck or Very Slow

A deployment seems stuck or is taking much longer than usual.

Solution:

1. Open the progress page and check the current stage and logs. Some stages can take several minutes.
2. If it's clearly stuck (no log updates for a long time), you can Cancel the deployment and try again.
3. If builds are consistently slow, check build size, number of dependencies, and Node version.

Cancel or Redeploy Not Working

Solution:

• Cancel - Only works for deployments that are not yet in a terminal state. If the deployment already finished, cancel is no longer available.
• Redeploy - Use after a deployment has finished. Ensure you're on the progress page for that deployment.

Custom Domain Issues

Domain Verification Failed

A custom domain shows Failed or stays in a configuring state without becoming Active.

Possible causes:

• DNS records not created or not propagated yet
• DNS connection invalid or zone/records not writable
• SSL certificate validation failed

Solution:

1. In Settings → Domains, click Retry for that domain
2. If you use Verify, ensure DNS has propagated (can take up to 48 hours). Then click Verify again.
3. Confirm your DNS connection is Active and has the correct zone
4. Check that the domain is in the selected zone (apex or subdomain of the zone name)

Add Domain Button Disabled

You cannot add a custom domain (button is disabled).

Cause: Custom domains require (1) at least one active DNS connection with zones, and (2) site infrastructure ready.

Solution:

1. DNS connection - Go to Connections → DNS Providers, add and validate a DNS connection
2. Site not ready - Wait until the site status is Active. Then open Settings → Domains again.

Delete Site Issues

Delete Site Failed: "Already Deleting"

You tried to delete the site and got Already Deleting.

Cause: The site is already in the process of being deleted.

Solution: Wait for the deletion to complete. Refresh the Cloud Deploy list; the site should disappear when deletion is done.

Delete Site Failed: "Resource In Use"

You tried to delete the site and got Resource In Use.

Cause: The site or its resources are still referenced by another process or dependency.

Solution:

1. Ensure no deployment is in progress for this site
2. Wait a few minutes and try delete again
3. If the error persists, contact support

Confirmation Text Doesn't Match

The Delete button stays disabled when you type in the confirmation field.

Cause: You must type the exact site name (case-sensitive, character for character).

Solution: Copy the site name from the modal or the site header and paste it into the confirmation field.

Quick Reference

Next Steps