What breaks when someone imports your n8n workflow

What breaks when someone imports your n8n workflow#

We submitted a workflow to the n8n template library. It came back rejected: sticky note text overlapping nodes. It looked fine on our screen. It did not on the reviewer's.

The cause was one missing property in the exported JSON. But when we imported that same file onto our own, newer instance six months later, it broke three more times for entirely different reasons.

This is about what an n8n export carries with it and what it does not — and why a file that runs on your machine may not run on anyone else's.

Layer one: the note that collapses itself#

Sticky notes carry width and height inside parameters. Drag a note's corner and both get written. Leave it untouched, or edit the JSON by hand, and they may be absent.

An absent width does not mean "keep what it looked like". On import n8n falls back to 240 pixels.

{
  "parameters": {
    "content": "## Qualify with AI\n\nThe bid qualification agent evaluates candidate tenders using an Anthropic chat model, an HTTP tool for tender details, and a structured output parser to produce consistent GO / NO-GO verdicts."
  },
  "type": "n8n-nodes-base.stickyNote",
  "typeVersion": 1,
  "position": [2048, 96],
  "name": "Sticky Note3"
}

In our session that note had been dragged wide, the paragraph sat on three lines, and the section frame comfortably enclosed the agent and all three of its sub-nodes. Two things follow from the collapse to 240 pixels.

The paragraph rewraps from three lines to eight and runs down to within a hair of the node beneath it. Exactly how far it overruns depends on font rendering: on the reviewer's screen it overlapped, on ours it clears by a few pixels. That variance is the point rather than a footnote — at 240 pixels the layout has no margin left, so whether it reads as "tight" or "broken" comes down to whose machine renders it.

The second problem from the same collapse#

The horizontal narrowing has a consequence that is harder to argue with. Two nodes end up outside any frame at all.

Fetch Tender Details and Parse Tender Verdict are sub-nodes of the agent. Visually they belong to the Qualify with AI section. Once the note narrows to 240 pixels they fall past its right edge, float between two sections, and their labels run together into one unreadable line.

Nobody notices this while building, because you read a canvas by proximity. A reviewer opening the file cold reads it by boundaries — and the boundaries said those two nodes belonged to nothing.

The fix, and a script#

We did not nudge the note by eye and resubmit, because eyeballing is what produced the problem. We recomputed the geometry and verified the result.

The diff touched only position, width and height. Node parameters, the agent prompt, the code nodes and every connection were verified unchanged. A layout fix that silently alters logic is worse than the layout problem.

The script checks four things: text fitting inside its note, text colliding with a node, notes overlapping each other, nodes overlapping each other.

python tools/validate_layout.py workflow.json

NODE_W, NODE_H = 200, 96
SUB_W, SUB_H   = 100, 100        # AI sub-nodes render smaller
STICKY_DEFAULT_W, STICKY_DEFAULT_H = 240, 160
CHAR_W, LINE_H, PADDING = 7.2, 21, 32

def rendered_text_height(content: str, width: int) -> int:
    """How tall the body renders at a given note width."""
    cols = max(int((width - 24) / CHAR_W), 1)
    lines = 0
    for raw in content.split("\n"):
        lines += max(1, -(-len(raw) // cols))   # ceiling division
    return lines * LINE_H + PADDING

def overlap(a, b) -> bool:
    ax, ay, aw, ah = a
    bx, by, bw, bh = b
    return ax < bx + bw and bx < ax + aw and ay < by + bh and by < ay + ah

The full script is in the repository alongside the rejected and corrected exports, so you can run it on both and see the difference.

Layer two: node versions#

The corrected workflow was accepted and published. Six months later we imported the same file onto our own, updated instance. The agent refused to work with a chat model:

This model is not supported in 2 version of the Agent node. Please upgrade the Agent node to the latest version.

An export pins every node's typeVersion to the moment of saving. The agent carried version 2. A freshly added agent node on the same instance came out as 3.1.

That is checkable in thirty seconds: drop a clean node on an empty canvas, export the mini-workflow, read its typeVersion. Then raise the value in your file.

TARGET = {
    "@n8n/n8n-nodes-langchain.agent":       3.1,
    "@n8n/n8n-nodes-langchain.chatTrigger": 1.4,
}

for node in workflow["nodes"]:
    want = TARGET.get(node.get("type"))
    if want and node.get("typeVersion", 0) < want:
        node["typeVersion"] = want

Layer three: the node that stopped existing#

With the agent version raised, the HTTP tool broke. The message said "Invalid URL", and the output panel carried the line that turned out to be the actual clue:

No parameters are set up to be filled by AI.

It turns out n8n has two different nodes for HTTP calls used as agent tools, and the export carried the older one.

The legacy node still renders its Placeholder Definitions section and a tip describing the {placeholder} syntax. Nothing fills them any more. The node reports that no parameters are set up to be filled, and the braces reach the API as literal text — hence an error about an invalid URL that has nothing to do with the URL.

The working form looks like this:

https://api.example.com/records/{{ $fromAI('record_id', 'Numeric record ID', 'string') }}

Two things are worth knowing. $fromAI resolves only when the node is connected to an agent as a Tool and the agent calls it — running the node on its own with "Execute step" passes the expression through unevaluated, which looks exactly like a broken URL. And for the same reason the preview under the URL field renders [undefined] at edit time. That is expected.

Layer four: the API underneath moves too#

The last one is not n8n's fault. The tool had dataField set to data.advertisement, and the register answered:

Target field "data.advertisement" not found in response. The response contained these fields: [status, data]

The response shape changed between the workflow being written and being run again. Nothing in n8n detects this, because as far as the platform is concerned the request succeeded.

That is the argument for a "last verified" field in your documentation, and for that date meaning "this is when we ran it" rather than "this is when we wrote about it".

Checklist before you submit#

1. Export the workflow, import it into a clean instance, and look at it there. Not at your editor tab.
2. Confirm every sticky has both width and height in parameters.
3. Confirm every node sits inside the frame that describes it, including AI sub-nodes.
4. Compare your nodes' typeVersion against what a freshly added node reports on your instance.
5. Check whether you are using a deprecated node type.
6. Run the whole workflow, not a single node.
7. Run the validation script.

The first point catches the most. The sixth is on the list because we lost half an evening testing an agent's tool in isolation from the agent.

Limitations#

The specific versions here will go stale. An agent typeVersion of 3.1 and the n8n-nodes-base.httpRequestTool type are current for n8n 2.8.4. The method of checking stays the same; the values will not.

The validation script checks geometry, not content. It passes on a workflow whose notes explain nothing.

We have no measurement of how often this hits other people. This is one submission and one import six months later, not a study.

What it comes down to#

The n8n template library renders your workflow from the file, on someone else's screen, with no memory of your session. So does anyone who downloads an export from your repository six months from now.

Everything that makes the workflow readable and runnable has to be written down explicitly. A sticky note without a width is not a note that keeps its size. It is a note that guesses, and it guesses at 240 pixels.