User Documentation

Going Live - Troubleshooting

Sign up for Upsun

Get your free trial by clicking the link below.

Get your Upsun free trial

If your site doesnโ€™t resolve after youโ€™ve made DNS changes, check potential solutions to common issues.

Verify DNS Anchor to this heading

On the command line using macOS, Linux, or the Windows Subsystem for Linux, run the following command:

host www.YOUR_DOMAIN

If your domain is, the response should be something like the following: is an alias for has address

If it isn’t, try the following steps:

  • Your DNS server might not be correctly configured or the old DNS records are still cached. Try removing your local DNS cache.
  • Set your computer’s DNS server to any Public DNS resolver (like CloudFlare or Google) to see if the issue is with the DNS server you are using.
  • Run ping www.YOUR_DOMAIN. If the result is different from what you got from running host www.YOUR_DOMAIN, you might need to remove your test settings.

Verify SSL/TLS encryption Anchor to this heading

To find out where your domain is pointing to, you can use the certificate checker tool. This tool provides guidance on certificates, including when you use a CDN. Check both the apex and the www domains to ensure they both point to your project.

For further investigations, run the following command in a shell:

curl -I -v  https://www.YOUR_DOMAIN

Look for error messages. Often the problem is caused by a mismatch between the certificate and the domain name or an expired custom certificate.

Error provisioning certificates Anchor to this heading

When a Let’s Encrypt certificate fails to provision after the build hook has completed, you get output similar to the following:

Provisioning certificates
  Validating 2 new domains
  E: Error validating domains: urn:ietf:params:acme:error:rejectedIdentifier :: The server will not issue certificates for the identifier :: NewOrder request did not include a SAN short enough to fit in CN
  Unable to validate domains domain, www.domain, will retry in the background.
  (Next refresh will be at 2023-04-28 02:22:50.639301+00:00.)
  E: Error: TLS Certificate provisioning failed

The renewal may fail because of the 64-character limit Let’s Encrypt places on URLs. If you have a branch with a long name, the environment URL is over this limit and the certificate is rejected. To solve this, shorten your branch name so it doesn’t exceed 20 characters.

Generated URLs for environments have the following pattern:

If you have a default domain set up, the generated URL has the following pattern:

The generated URLs consist of:

  • YOUR_DOMAIN = the amount of characters your domain has
  • ENVIRONMENT = BRANCH_NAME + 7 character hash
  • PROJECT_ID = 13 characters
  • REGION = 2 to 4 characters, depending on the region
  • = 15 characters
  • extra characters like . and - = 4 to 5 characters, depending on if you have a default domain

This leaves you with 21 to 23 characters for your branch name (BRANCH_NAME) without exceeding the 64-character limit, depending on the region. To ensure your renewals succeed, keep your branch names under 20 characters.

Ownership verification Anchor to this heading

To provide a valid TLS-certificate, the certificate issuer checks that the requester is entitled to receive the requested certificate. This check is known as the Challenge step.

The certificate request is generated based on your routes definition. If you want your site to be available with and its subdomain, make sure both are defined in your routes.

To pass this verification, there are requirements you need to meet. checks that all the routes you defined are pointing to your project. For the challenge to complete, domains and subdomains must point directly to your project.

Otherwise, you get an error similar to:

  E: Error validating domain Couldn't complete challenge [HTTP01: pending | DNS01: pending | TLSALPN01: pending]
  Unable to validate domains, will retry in the background.

When you use a CDN, to ensure the challenge succeeds, check that:

  • Your domains and subdomains point to your CDN
  • The _acme-challenge. subdomain, as in, points to your CDN
  • The /.well-known/ route, as in, is accessible with no redirects

If you don’t follow those requirements, you get an error message similar to:

  W: Failed to verify the challenge at the gateway for the domain ''
  E: Error validating domain Couldn't complete challenge [HTTP01: The client lacks sufficient authorization]

For more information, see how to setup your CDN. For more details regarding the challenge step, consult your certificate issuer’s documentation. A common issuer is Let’s Encrypt.

Make sure that the apex domain and its www subdomain are both pointing where needed. Note that it can take up to 72 hours for DNS changes to be effective. For more information, see how to set up a custom domain.

If the changes take longer than expected, redeploy the impacted environment.

Also make sure that no conflicting DNS records exist for your domain. For example, a conflicting AAAA (IPv6) DNS record can result in a [HTTP01: The client lacks sufficient authorization] error.

If the certificate generation issue persists, check if an outage is ongoing with your certificate issuer (the most common one is Let’s Encrypt) and with your CDN provider if you have one. If not, contact Support.

Check your routes configuration Anchor to this heading

Certificates are generated based on your routes configuration. When a certificate is renewed, the renewal bot checks that all of the defined routes can be accessed. If at least one of the routes defined in your .platform/routes.yaml file can’t be accessed, the renewal fails and the following error is displayed:

Provisioning certificates
  Validating 2 new domains
  W: Failed to verify the challenge at the gateway for the domain ''
  E: Error validating domain Couldn't complete challenge [HTTP01: There was a problem with a DNS query during identifier validation]
  Unable to validate domains, will retry in the background.
  (Next refresh will be at 2023-07-04 17:43:10.259891+00:00.)
  - certificate 61bc4c8: expiring on 2023-09-02 01:11:12+00:00, covering

E: Error: TLS Certificate provisioning failed

For example, if you add and to your routes configuration but the www subdomain doesn’t point to your project through a CNAME record, the certificate renewal fails. For the renewal to succeed, add the missing CNAME record to your DNS or remove (and any other www route) from your .platform/routes.yaml file.

Verify your application Anchor to this heading

Check your app’s logs and look for anomalies. On the command line type platform logs app and platform logs error.

Use ASCII for the domain Anchor to this heading expects an ASCII representation of your domain. To use an internationalized domain name (IDN), convert it to ASCII. Use a tool such as the conversion tool provided by Verisign.

Something still wrong? Anchor to this heading

For more general information, see how to troubleshoot development.

If your website is still not working as expected, contact support.

Is this page helpful?