DEV Community

Cover image for Valid JSON Doesn't Mean a Valid n8n Workflow: What Static Analysis Can Catch
Ro
Ro

Posted on Fully Autonomous

Valid JSON Doesn't Mean a Valid n8n Workflow: What Static Analysis Can Catch

When building automations with n8n, it's easy to assume that an exported workflow is structurally valid as long as its JSON parses successfully.

But valid JSON only tells us that the file follows JSON syntax. It doesn't tell us whether the nodes and their connections form a consistent workflow.

While developing an open-source workflow inspector, I explored several issues that can be detected without executing an automation.

1. Connections referencing missing nodes

Imagine a workflow containing nodes named Fetch Records and Format Response.

Now imagine one of its connections still references a node called Notify User, which no longer exists.

The JSON may parse correctly, but the connection points to a missing destination.

A static analyzer can detect this by:

  • Reading the list of nodes.
  • Building an index of their names.
  • Traversing the workflow's connections.
  • Checking whether each referenced destination exists.
  • Reporting inconsistencies before execution.

This doesn't require running the workflow or connecting to an n8n instance.

2. Disconnected and isolated nodes

Another useful check involves nodes that are disconnected from the rest of a workflow.

These aren't necessarily errors. Sometimes a developer intentionally keeps an unused node for experimentation.

That's why a static analyzer should distinguish definite structural inconsistencies from findings that require human review.

An isolated node might deserve an informational finding rather than a critical error.

3. Duplicate identifiers and unexpected cycles

Other structural checks include duplicate node identifiers, repeated connections and cycles within a workflow's main connections.

A cycle isn't automatically a bug, but it may deserve inspection depending on the workflow's intended behavior.

The goal is to highlight situations worth reviewing, not to claim that every unusual structure will fail at runtime.

4. What static analysis cannot tell you

Static analysis has important limitations.

It cannot reliably establish whether external APIs are reachable, credentials are valid, or a particular execution will succeed.

It also shouldn't automatically classify every disconnected group or cycle as an error.

The most useful reports explain what was detected, why it matters and what the developer should inspect next.

An open-source implementation

I've been exploring these ideas while building Workflow Inspector, a small independent browser-based tool for analyzing exported n8n workflow JSON files.

The initial version includes ten structural checks and processes the workflow locally without executing it or uploading its contents.

The project is open source under Apache-2.0.

Source: https://github.com/roglz/workflow-inspector

Demo: Try Workflow Inspector

The project is not affiliated with n8n.

I'm particularly interested in the distinction between definite structural errors and findings that should remain advisory.

Which structural problems do you think are worth checking before running an n8n workflow?

Top comments (0)