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:
- For a site on Netlify, go to .
# 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.
Did you find this doc useful?
Your feedback helps us improve our docs.