This document provides a collection of tips and solutions to help you integrate with Builder effectively. It covers common scenarios such as resolving API key mismatches, fixing model name discrepancies, handling common errors and enabling data-bindings in Node environments.
If you get a message in the Visual Editor that there's an API Key mismatch, it means that Builder and your codebase are using different API keys.
- Check the API Key: Since each Space has its own Public API Key, if you have more than one Space in your Organization, make sure you are using the Public API Key for the intended Space.
- Verify the API Key in Builder: To confirm that you're using the correct Public API Key, check that the API Key in your codebase and the Public API Key in Builder for the intended Space are the same.
If you get a message in the Visual Editor that there's a model name mismatch, it means that the Builder model name and the code component name in your codebase aren't the same.
To confirm that you're using the correct model name:
- In Builder, go to Models.
- Open the model in question and go to Advanced.
- Make sure the Unique Identifier is the same as the model name of the component in your codebase.
If you're getting a 404 but aren't sure why, check these things:
- Make sure you've published your Page: In Builder, click the Publish button in the upper right corner of the Visual Editor.
- Check the URL: If you name the page
test2for example, Builder adds a hyphen, so that the URL segment istest-2. - Set the Preview URL: Make sure that you've set the preview URL on the Page Model.
- Restart the dev server: For some frameworks, you might have to restart the dev server.
If using Next.js, you may notice that your content changes do not show up on your website as quickly as you might like after publishing in Builder. This is due to the caching strategies Next.js uses by default. If you are experiencing this issue, consider modifying your Next.js cache settings.
For example, the following code changes the behavior of the request from indefinitely caching fetch calls to caching for 5 seconds.
See the Next.js documentation, particularly Caching in Next.js, to learn how to modify those settings. There you will find information on Opting Out from caching fetch request responses and Opting Out of Full Route Cache.
In certain Node server environments, the builder SDK may require additional initialization steps, namely the initialization of a package called isolated-vm (used to safely evaluate your data bindings).
On Apple Silicon Macs using Node v20, isolated-vm can crash and break SSR in local environments. To prevent this, prepend NODE_OPTIONS=--no-node-snapshot to your start, dev, and build scripts. Production environments are not affected.
Starting with Chrome 142, you might encounter an error when using Builder's Visual Editor to preview localhost content. The error appears as:
Failed to load resource: net::ERR_BLOCKED_BY_LOCAL_NETWORK_ACCESS_CHECKThis error prevents the Visual Editor from connecting to your localhost, making it impossible to preview your content during development.
Chrome 142 introduced a new security feature that restricts websites from accessing your local network. When Builder's Visual Editor first attempts to connect to your localhost URL, Chrome displays a permission prompt asking you to allow or block local network access. If you select block, the Visual Editor cannot connect to your local development server.
To fix this issue:
- In Chrome, go to chrome://flags/#local-network-access-check.
- Set the Local Network Access option to Default. Make sure it's not set to Enabled or Enabled blocking.
- Restart Chrome when prompted.
- Reload the Builder Visual Editor and attempt to preview your localhost URL again.
- When Chrome displays the permission prompt, select Allow.
The screenshot below shows the Local Network Access Checks setting in Chrome flags with the Default setting selected.
This restriction is part of Chrome's security measures to protect against cross-site request forgery (CSRF) attacks targeting local network devices. For more information, see Google's announcement: New permission prompt for Local Network Access.