Skip to main content
Log inGet free account
Last Reviewed: March 23, 2023

Known Issues and Troubleshooting

Review known issues and solutions.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

This section provides information on known issues and solutions to common troubleshooting scenarios.

Known Issues

A repository can only be associated with one Front-End Site
A repository can only be associated with one Front-End Site at a time. You will receive an error message if you attempt to connect a repository to two or more sites.
Gatsby does not support SSR and DSG
Server-side Rendering and Deferred Static Generation (DSG) for Gatsby v4 are currently not supported.
Manual support is required
Manual support is required for domain and DNS setup.
Preview functionality is not supported for Gatsby
Preview functionality is not currently supported for Gatsby. Currently, it is only available for Drupal sites.
Renaming a linked repository in GitHub will cause a break in your decoupled experience.
Renaming a linked repository in GitHub is not recommended, as it will cause a break in your experience. In the event a user renames an attached Git repository on GitHub and disconnects the Git repository and attaches the renamed site, this will trigger a false live-build and the Front-End Site will be in a persistent build log state that cannot be canceled. To fix this issue, disconnect the renamed Git repository and revert to the original name. This action will instantly restore all data. Renaming the Git repository on GitHub to the original name should fix the build process.
Select files can cause build errors

Select files, such as .dockerignore and .gcloudignore files can cause build errors or failed builds. Removing these files from source and adding them to .gitignore solves the issue.

Users must have permissions to enable decoupled for GitHub organization accounts.
Users must have permissions to enable Front-End Sites for GitHub organization accounts. The user should be the Owner of the account. GitHub organization owners can allow other users to manage the Pantheon GitHub application on their behalf.
How to uninstall a VCS

Uninstalling a GitHub application successfully requires manual intervention by the Pantheon Support team. Reach out to Support if you need to uninstall your GitHub application to connect and reinstall to a different GitHub account. If you have attempted to uninstall on your own and are unable to proceed, reach out to Support to correct your account.

Next.js 13 App Router

The caching recommendations outlined for use with our Next.js starter kits are currently only compatible with the Next.js Pages Router, not the App Router.

Troubleshooting

Build works locally but won't build on Pantheon

Follow the steps below if your build works locally but won't build on Pantheon.

  1. Make sure any environment variables you have locally are set in the site’s Dashboard.

  2. Verify that your scripts in package.json have an explicit step for build and start. For example:

    "scripts":{
"build": "next build",
"start": "next start"
}
    • If the build and start steps have a different name, specify it in the Dashboard in the Advanced Settings section when creating a site. You can also specify this in the Builds section of the site’s dashboard.

Images are not showing up on my Next.js site

Consult the Next.js docs on their image component. Set the IMAGE_DOMAIN environment variable if the images are coming from a domain that is different from your liked CMS.

Make sure you are passing the IMAGE_DOMAIN as a prefix to the src prop if you are using the next/image component. Refer to Next.js documentation for more information.

The Decoupled Drupal health check is failing with BackendNotSetError

In order for your site to build successfully, your decoupled Front-End must point to a valid CMS endpoint. This is done through the use of the BACKEND_URL or PANTHEON_CMS_ENDPOINT environment variables. Only one of these environment variables is required to be set.

If used, the BACKEND_URL variable should be set to the URL of your CMS site. If you choose to use the PANTHEON_CMS_ENDPOINTvariable, it should be set to the URL of your CMS site without protocol. For example:

BACKEND_URL -> "https://dev-my-drupal-site.pantheonsite.io"
PANTHEON_CMS_ENDPOINT -> "dev-my-drupal-site.pantheonsite.io"

In order to set an enviornment variable through the Pantheon Dashboard, navigate to your sites Overview > Settings > Builds page and scroll down to Site Environment Variables. Add the key of your environment variable and it's corresponding value.

To mock a backend for local development, define it in your projects .env.development.local file: For example:

BACKEND_URL="https://dev-my-drupal-site.pantheonsite.io"
// Or
PANTHEON_CMS_ENDPOINT="dev-my-drupal-site.pantheonsite.io"