Fixing “Could not load workflow preview” in n8n

If you have ever opened an n8n workflow or custom node and been greeted with the message “Could not load workflow preview. You can still view the code and paste it into n8n”, you know how annoying it can feel, especially when you are in the middle of building or debugging. The good news is that this error is usually very fixable with a few targeted checks.

In this guide, we will walk through what is actually going on behind that message, why previews sometimes fail, and a practical checklist you can follow to get your custom nodes (including ones like n8n-nodes-mcp) showing up properly again. Think of it as a friendly debugging companion you can keep open next to your editor.

What this n8n error really means

When n8n shows “Could not load workflow preview”, it is basically saying: “I can see the workflow JSON and node references, but I cannot safely render them inside the editor.”

The preview you see in the n8n editor is generated from two main things:

• Your workflow JSON
• The node definitions that n8n is able to load from your installed or custom node packages

If anything goes wrong while loading those node bundles or resolving their metadata, the editor gives up on the preview and falls back to letting you view the raw JSON instead.

Most common reasons the workflow preview fails

There are a handful of issues that cause the majority of these preview errors. In almost every case, the root problem is related to how your custom node bundle is built, loaded or configured.

• Missing or invalid node bundle – the custom node package did not compile, or the main entry is wrong or missing, so n8n cannot load the node metadata.
• Dependency mismatch – your node package is using a different Node.js runtime version or incompatible versions of n8n-workflow or other peer dependencies.
• Build / TypeScript issues – TypeScript was never compiled to JavaScript, or the bundler failed and left you with no usable JS output.
• Runtime errors on import – the node throws an error as soon as n8n tries to require or import it, for example due to syntax errors or missing imports.
• Incorrect placement or configuration – n8n simply cannot find your custom node because it is in the wrong folder or not referenced correctly in your n8n setup.

The rest of this article is about how to narrow down which of these is happening in your case and how to fix it as quickly as possible.

First things to check when you see “Could not load workflow preview”

Before diving into deep debugging, a couple of quick checks can often point you straight to the problem.

• Check your browser devtools console
  Open the console on the page where the preview fails. Look for the first error message or stack trace. It often points directly to a missing bundle, a failing import or a bad script.
• Look at your n8n server logs
  Check the terminal where n8n is running or your Docker logs. If needed, increase verbosity by setting:

  N8N_LOG_LEVEL=debug

  Then restart n8n and watch what happens when you open the workflow.

• Confirm your Node.js version
  Make sure your runtime matches what n8n and your custom node expect. For modern n8n versions, Node 18 or higher is usually required.
• Verify the custom node build output
  Open the folder for your custom node package and confirm:
  • A build folder (often dist) exists.
  • There is a package.json with a valid main or module field pointing to compiled JavaScript.

Step-by-step troubleshooting guide

Let us walk through a practical sequence you can follow. You do not have to do every step in every situation, but going down this list usually uncovers the issue.

1. Make sure Node and n8n versions are compatible

Version mismatches are a very common source of strange, hard-to-understand errors. Start by confirming which Node.js version you are actually using:

node -v
# If using nvm
nvm use 18

For many setups in 2024 and beyond, Node 18 or newer is expected by n8n and by most custom node bundles. If you are on an older version, upgrade or switch via nvm and restart n8n.

2. Inspect package.json and check the built output

Your custom node package, for example n8n-nodes-mcp, needs to expose a JavaScript file that n8n can require. That is controlled by package.json and your build step.

Open package.json in your custom node and verify:

• main points to a JavaScript file, such as dist/index.js.
• A build or dist folder exists and actually contains compiled JS files.

If your repository only has .ts files and no compiled .js, n8n will not be able to load your node.

Typical build steps for a TypeScript-based node look like this:

# Install dependencies
npm install

# Build the project
npm run build

# Or, if the project uses tsc directly
npx tsc

If the build fails, read through the error messages carefully. Common culprits include missing type definitions, incorrect import paths or misconfigured Babel / TypeScript settings. Fix those, rebuild, and check that the expected JS files appear in the output folder.

3. Check peerDependencies and n8n-workflow compatibility

Many custom n8n nodes declare peerDependencies so they can rely on the versions already installed by n8n instead of bundling their own copies. A mismatch here can easily cause runtime errors that break the preview.

What to look at:

• Open package.json (and optionally your lockfile) and find the peerDependencies section.
• Check the declared version of n8n-workflow and confirm it is compatible with the n8n version you are running.
• If versions are out of sync, align them by upgrading or downgrading the custom node package or by adjusting the peer dependency range.

For example, you might see something like:

peerDependencies: { "n8n-workflow": "*" }

A wildcard like this can work, but you should still be sure the actual runtime version of n8n-workflow matches what your code expects.

4. Rebuild your node and restart n8n

Once you have fixed any build or dependency issues, rebuild the package and restart n8n so it can rescan the custom nodes. This step is easy to forget, and then nothing seems to change.

# Local development example
npm run build
npm restart n8n

# Docker example (replace container name if needed)
docker restart n8n

If you are using n8n Desktop or another GUI-based setup, stop the server, start it again, then refresh the editor page with a hard reload (for example, Ctrl+F5) to clear cached bundles.

5. Turn on detailed logging and watch for runtime errors

Sometimes the preview fails because of an error that only shows up in logs, not directly in the UI. In those cases, enabling debug logging is incredibly helpful.

export N8N_LOG_LEVEL=debug
n8n start

Then trigger the problem again by opening the workflow preview. Watch the logs for any errors that mention your custom node or its files.

At the same time, keep an eye on the browser console. Look for messages like:

• Uncaught ReferenceError
• TypeError

These often include a stack trace pointing to your node bundle or a specific import that could not be resolved. That first error is usually the most important clue.

6. Validate your node metadata and description structure

n8n uses metadata that each node exports to render the node in the editor. If the description object is malformed or throws an error during import, the preview cannot be rendered.

A couple of guidelines for safe node metadata:

• Make sure the exported description object is valid and does not rely on code that might throw during module import.
• Avoid running heavy or asynchronous logic at the top level of the module. Keep side effects inside the execute() method or other runtime functions.

If metadata loading fails, the editor cannot safely show your node, which leads to the preview error you are seeing.

Example checklist for a typical TypeScript custom node

If you are working with a TypeScript-based custom node, here is a quick checklist you can use as a sanity check:

1. Run node -v and confirm Node is version 18 or higher.
2. Run npm ci or npm install and ensure it completes without errors.
3. Run npm run build and verify that it succeeds and produces a dist folder.
4. Open package.json and confirm main points to something like dist/index.js.
5. Restart the n8n server after building so it reloads the updated bundle.
6. Check server logs and the browser console to make sure there are no require/import errors related to your node.

Special considerations for monorepos and workspace setups

If your project lives inside a monorepo or uses tools like pnpm or Yarn workspaces, resolution can get a bit more complex. Your lockfile or template snippet might show a long list of packages and versions, which is a sign that the dependency graph is being managed at the workspace level.

In these setups, make sure that the environment running n8n can actually resolve your custom node package correctly. A few tips:

• Confirm that the compiled package is accessible from the n8n runtime, not just from the workspace root.
• Consider bundling or publishing the compiled node package, then placing that built version directly into the directory where n8n expects custom nodes.
• Double-check that symlinks or workspace paths are resolved correctly inside Docker or other containerized environments.

When it is ok to just copy the workflow JSON into n8n

Sometimes you just need to keep moving, even if the preview is broken. That is where the “You can still view the code and paste it into n8n” message comes in handy.

Copying the workflow JSON into n8n directly lets you continue testing the workflow logic, even if the editor cannot render the preview. It is a useful workaround when you are blocked, but keep in mind:

• This does not fix the underlying problem with your custom node bundle.
• You will still want to go through the build and compatibility checks above to restore a fully working preview.

Quick summary of the most effective fixes

If you want a short recap of what usually solves the “Could not load workflow preview” error, here it is:

• Make sure the project is built and that JavaScript output is available.
• Verify that main in package.json points to compiled JS, not raw TypeScript.
• Check your Node.js version and match it with n8n’s requirements, typically Node 18+.
• Ensure peer dependencies like n8n-workflow are compatible with your n8n version.
• Inspect n8n server logs and the browser console, and focus on the first error or stack trace.
• Restart n8n after making changes so it reloads your custom node bundles.

What to share when asking for help

If you have gone through the checklist and the preview still refuses to load, you might want to ask for help on GitHub, Discord, Stack Overflow or similar communities. To make it easier for others to help you quickly, include:

• Your n8n version and Node.js version.
• The first relevant error messages from the server logs and browser console, including stack traces.
• A snippet of your package.json showing main, scripts and peerDependencies.
• A short description of your build output, for example a list of files inside your dist folder.

Wrapping up

In most cases, “Could not load workflow preview” in n8n comes down to a loading or runtime issue with your custom node bundle rather than anything wrong with the workflow itself. By confirming your Node and n8n versions, checking the build output, aligning dependencies and reviewing logs, you can usually track down the problem and get your previews working again.

If you are stuck on a specific setup, feel free to share the first browser console error and the relevant part of your package.json or build log. Walking through those details step by step often reveals the exact line that needs to change.

Want a quick sanity check? Share the top two or three lines from your n8n server log or browser console error, and we can pinpoint the minimal fix so you can get back to building.