Troubleshoot visual editor setup

Get help setting up the visual editor for your site.

Beyond setup

For ongoing troubleshooting help after you’ve set up your visual editor, check out Troubleshoot visual editor or our official Support Guides.

Site framework setup required

If your site relies on a framework or setup that uses SSG (or Static site generator) architecture, then you will need to configure the visual editor for SSG.

For example, you may need to include the ssgName or ssg property in your visual editing configuration file.

Examples using the ssgName property

• Next.js and Contentful starter site
• Astro and Sanity
• Next.js and Git as the content source (Git CMS)

Configuration file help

Many setup errors can happen if the visual editor configuration file is misconfigured or missing.

The visual editor requires a properly configured stackbit.config.ts that tells the visual editor how to understand the content structure of your site and where to find its content files.

For examples of working configuration files, check out the stackbit.config.ts file of these template site repositories:

Site repository	Content source	Optimized for
TypeScript + MUI Starter	Git CMS	- a tutorial-like experience - learning about visual editor capabilities
ContentOps Starter	Git CMS	- learning about content types with over 35 content types - try more complex content type scenarios
Auto-annotated portfolio	Git CMS	- learning about auto annotating your site - lots of auto annotated components
Next.js & Contentful Starter	Headless CMS: Contentful	getting started with Contentful
Astro & Sanity Starter	Headless CMS: Sanity	getting started with Sanity

What is Git CMS?

For the visual editor, Git CMS refers to storing content in files and managing them directly in those files with Git version control.

GitHub App installation errors

You may find various errors when you try to install the GitHub App for the Netlify visual editor.

To troubleshoot these, we recommend the following:

• Go to your GitHub App settings to check if the GitHub App for the Netlify visual editor is already installed and for which GitHub account. Noting that you may have installed the app for a different GitHub account than the one where the site repo is installed. To learn more, check out the managing app permissions GitHub docs.

BitBucket access key errors

If your BitBucket access key is failing, we recommend confirming you’re using the right access key. To learn more, check out the BitBucket access key docs.

Works locally but not on Netlify

If you find the visual editor works locally but on Netlify, check that your local updates to the visual editor configuration file (stackbit.config.ts) are also merged to your remote site repository.

For example, if your site map works locally but on Netlify you have a missing site map error, then confirm that your local updates are on the configured working branch for the visual editor. So if your working branch is set to preview on Netlify, confirm that these changes have been pushed to your remote repository.

To check your remote working branch on Netlify:

1. For a site on Netlify, go to Project configuration > Visual editor > Preview settings.

Site Framework related error

Your site’s framework may require additional configuration for the visual editor to work. To learn more, check out the visual editing framework docs or check out the configuration file (stackbit.config.ts) of some template site repositories.

Learn more about what your framework may require to set up the visual editing.