Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

fix(n8n): send only the fields the workflow API accepts (#413)

richardhxwangd71d4a240b57
diff --git a/n8n/agent-harness/cli_anything/n8n/n8n_cli.py b/n8n/agent-harness/cli_anything/n8n/n8n_cli.py
index 390ee85e2..b1f2e7ec4 100644
--- a/n8n/agent-harness/cli_anything/n8n/n8n_cli.py
+++ b/n8n/agent-harness/cli_anything/n8n/n8n_cli.py
@@ -45,9 +45,71 @@ def _safe_filename(name: str) -> str:
return name[:60] or "workflow"
-# Fields to strip when sending workflow data to n8n API
+# Server-owned fields, stripped from workflow data kept locally (backups, diffs) so
+# instance-specific noise does not drown the actual content.
_INTERNAL_FIELDS = frozenset({"id", "createdAt", "updatedAt", "versionId", "shared"})
+# Fields n8n accepts in a create/update body: the non-readOnly properties of the
+# public API workflow schema
+# (packages/cli/src/public-api/v1/handlers/workflows/spec/schemas/workflow.yml).
+# That schema sets additionalProperties:false and marks `active`, `tags`, `meta`,
+# `isArchived`, `triggerCount` and the id/timestamp fields readOnly, so sending any
+# of them rejects the entire request with 400. `active` and `tags` are changed
+# through their own endpoints (activate/deactivate, PUT /workflows/{id}/tags).
+# Checked against the schema on n8n 2.16.1 and 2.33.3; `nodeGroups` and
+# `parentFolderId` only exist on the latter, and are listed so an edit made against
+# a newer instance does not silently drop node groups or move a workflow to the root.
+_API_WRITABLE_FIELDS = frozenset({
+ "name", "description", "nodes", "connections", "settings",
+ "staticData", "pinData", "nodeGroups", "parentFolderId",
+})
+
+# Of those, the ones that are nullable in the schema. For them null is meaningful —
+# it clears the stored value, whereas omitting the key leaves it alone — so their
+# nulls have to be forwarded. `versions rollback` depends on this: a snapshot taken
+# before any pinned data was added carries `pinData: null`, and dropping it would
+# leave today's pinned data in place while reporting a successful rollback.
+# `parentFolderId` documents null as "move it to the project root".
+# The rest are non-nullable (`description` is a plain string), and echoing back the
+# null that a GET returned is rejected outright.
+_API_NULLABLE_FIELDS = frozenset({"staticData", "pinData", "parentFolderId"})
+
+# Writable, but only present from n8n 2.33.3. An older instance does not define them
+# and rejects the request outright, so a file exported from a newer one cannot be
+# imported as-is. Rather than probe the target's version, the write is retried
+# without them — losing a canvas grouping beats losing the whole import.
+_NEWER_SCHEMA_FIELDS = frozenset({"nodeGroups", "parentFolderId"})
+
+# The nested settings object sets additionalProperties:false as well (schemas/
+# workflowSettings.yml). n8n's own editor stores keys the public API does not define
+# — `binaryMode` is written into every workflow created in the UI — so settings read
+# back from the server have to be reduced too, or the whole request is rejected with
+# `request/body/settings must NOT have additional properties`.
+_API_WRITABLE_SETTINGS = frozenset({
+ "saveExecutionProgress", "saveManualExecutions", "saveDataErrorExecution",
+ "saveDataSuccessExecution", "executionTimeout", "errorWorkflow", "timezone",
+ "executionOrder", "callerPolicy", "callerIds", "timeSavedPerExecution",
+ "availableInMCP",
+ # Added by 2.33.3. Listed for the same reason as the top-level ones: on a current
+ # instance these are writable, and omitting them would silently reset the user's
+ # choice. `binaryMode` in particular is written by the editor into every workflow.
+ "binaryMode", "credentialResolverId", "customTelemetryTags",
+ "redactionPolicy", "timeSavedMode",
+})
+
+# The nested counterpart of _NEWER_SCHEMA_FIELDS: settings properties an older
+# instance does not define, which its additionalProperties:false rejects.
+# The validator's wording for an unexpected property, and the only two error paths
+# the compatibility retry knows how to reduce. Anything deeper — an unexpected member
+# inside a node or a grouping — is malformed input, not a version difference.
+_UNKNOWN_PROPERTY_SUFFIX = " must NOT have additional properties"
+_REDUCIBLE_ERROR_PATHS = frozenset({"request/body", "request/body/settings"})
+
+_NEWER_SCHEMA_SETTINGS = frozenset({
+ "binaryMode", "credentialResolverId", "customTelemetryTags",
+ "redactionPolicy", "timeSavedMode",
+})
+
def _conn(ctx: click.Context) -> dict[str, str]:
"""Extract connection kwargs from Click context."""
@@ -59,10 +121,168 @@ def _json_flag(ctx: click.Context) -> bool:
def _clean_for_api(data: dict[str, Any]) -> dict[str, Any]:
- """Remove n8n internal fields before sending to API."""
+ """Keep only the fields n8n accepts in a workflow create/update body.
+
+ Nulls are dropped for the non-nullable properties: `description` is a plain
+ string in the schema, so echoing back the null a GET returned is rejected with
+ `request/body/description must be string`, and omitting the key instead leaves
+ the stored value untouched. Nulls for `_API_NULLABLE_FIELDS` are kept, because
+ for those null is the only way to clear the value.
+
+ `settings` is required and has its own additionalProperties:false, so it is
+ always present and always reduced.
+ """
+ body = {
+ k: v for k, v in data.items()
+ if k in _API_WRITABLE_FIELDS and (v is not None or k in _API_NULLABLE_FIELDS)
+ }
+ settings = body.get("settings")
+ if isinstance(settings, dict):
+ body["settings"] = {k: v for k, v in settings.items() if k in _API_WRITABLE_SETTINGS}
+ elif settings is None:
+ body["settings"] = {} # required by the schema; absent in older exports
+ # Anything else is left untouched, so the server rejects it by name rather than
+ # this quietly replacing what the caller wrote with an empty object.
+ return body
+
+
+def _strip_server_fields(data: dict[str, Any]) -> dict[str, Any]:
+ """Drop server-owned fields from a workflow kept locally.
+
+ Unlike _clean_for_api this preserves state such as `active` and `tags`, which a
+ backup has to record and a diff has to compare even though neither can be sent
+ back through the workflow endpoint.
+ """
return {k: v for k, v in data.items() if k not in _INTERNAL_FIELDS}
+def _diag(msg: str) -> None:
+ """Warn on stderr, so `--json` output stays parseable.
+
+ `warn()` prints to stdout (repl_skin.py), which is fine for the interactive
+ commands that use it but would corrupt the documented machine-readable output
+ exactly when one of these fallbacks fires. repl_skin.py is a verbatim copy of the
+ plugin's and is meant to stay that way, so this goes around it rather than
+ changing it.
+ """
+ click.secho(f" ⚠ {msg}", fg="yellow", err=True)
+
+
+def _without_newer_schema_fields(payload: dict[str, Any]) -> tuple[dict[str, Any], set[str]]:
+ """Strip properties that only exist in newer n8n schemas, top level and nested.
+
+ `settings` carries its own additionalProperties:false, so an incompatible key in
+ there fails the request just as a top-level one does — dropping only the outer
+ ones would retry and fail again.
+ """
+ dropped = set(_NEWER_SCHEMA_FIELDS) & set(payload)
+ reduced = {k: v for k, v in payload.items() if k not in _NEWER_SCHEMA_FIELDS}
+ settings = reduced.get("settings")
+ if isinstance(settings, dict):
+ in_settings = _NEWER_SCHEMA_SETTINGS & set(settings)
+ if in_settings:
+ reduced["settings"] = {
+ k: v for k, v in settings.items() if k not in _NEWER_SCHEMA_SETTINGS
+ }
+ dropped |= {f"settings.{k}" for k in in_settings}
+ return reduced, dropped
+
+
+def _is_unknown_property_error(exc: requests.exceptions.HTTPError) -> bool:
+ """True when a 400 says the payload has a property the target does not define.
+
+ The suffix alone is not enough: the validator reports the same wording for an
+ unexpected member nested anywhere, and only the two levels this retry actually
+ reduces are safe to act on.
+
+ retryable request/body must NOT have additional properties
+ request/body/settings must NOT have additional properties
+ not retryable request/body/nodes/0 must NOT have additional properties
+ request/body/nodeGroups/0 must NOT have additional properties
+ request/body/description must be string
+ request/body/settings/executionTimeout must be number
+
+ The third line is the dangerous one: malformed input inside a grouping would
+ otherwise be read as a version mismatch, and dropping the whole grouping could
+ turn an invalid request into a success that quietly lost data.
+ """
+ try:
+ message = str(exc.response.json().get("message", ""))
+ except (ValueError, AttributeError, TypeError):
+ return False
+ if not message.endswith(_UNKNOWN_PROPERTY_SUFFIX):
+ return False
+ return message[: -len(_UNKNOWN_PROPERTY_SUFFIX)] in _REDUCIBLE_ERROR_PATHS
+
+
+def _send_workflow(send: Any, payload: dict[str, Any]) -> Any:
+ """Send a workflow write, retrying once without newer-schema-only properties.
+
+ Importing a file exported from n8n 2.33.3+ into an older instance fails on
+ `nodeGroups` / `parentFolderId`, which that schema does not define. The target's
+ version is not exposed anywhere cheap to query, so this reacts to the rejection
+ instead and says what it dropped.
+ """
+ try:
+ return send(payload)
+ except requests.exceptions.HTTPError as exc:
+ if getattr(exc.response, "status_code", None) != 400:
+ raise
+ if not _is_unknown_property_error(exc):
+ raise
+ reduced, dropped = _without_newer_schema_fields(payload)
+ if not dropped:
+ raise
+ # Say what is known — a 400 with these keys present — rather than asserting
+ # they caused it. The retry is a guess; if it fails the real error stands.
+ _diag(f"Write rejected with 400 — retrying without {', '.join(sorted(dropped))}")
+ return send(reduced)
+
+
+def _create_workflow(payload: dict[str, Any], conn: dict[str, str]) -> Any:
+ return _send_workflow(lambda body: workflows.create_workflow(body, **conn), payload)
+
+
+def _update_workflow(workflow_id: str, payload: dict[str, Any], conn: dict[str, str]) -> Any:
+ return _send_workflow(lambda body: workflows.update_workflow(workflow_id, body, **conn), payload)
+
+
+def _reapply_tags(workflow_id: str | None, tags: Any, conn: dict[str, str]) -> None:
+ """Restore tag assignments through the endpoint that owns them.
+
+ `tags` is readOnly on the workflow body, so anything that recreates or rewinds a
+ workflow leaves them behind unless they are set separately. Passing None means
+ the source did not record any (an older export, say) and the current assignment
+ is left alone; an empty list means the source had none and clears them.
+
+ Tag ids are per-instance, so restoring into a different n8n answers
+ `404 Some tags not found`. That is reported rather than raised — the workflow
+ itself is already in place, and failing the whole restore over it would be worse.
+ """
+ if not workflow_id or tags is None:
+ return
+ if not isinstance(tags, (list, tuple)):
+ # A scalar here would raise on the comprehension below — after the workflow
+ # has already been created, so the caller would report a failure for
+ # something that exists, and a retry of restore-all would duplicate it.
+ _diag(f"Tags on {workflow_id} are not a list — left unchanged")
+ return
+ tag_ids = [{"id": t["id"]} for t in tags if isinstance(t, dict) and t.get("id")]
+ if tags and not tag_ids:
+ # The source recorded tags but none of them carry an id. Sending the empty
+ # list here would clear the assignment, which is the opposite of what an
+ # unreadable record should do.
+ _diag(f"Tags on {workflow_id} could not be read from the source — left unchanged")
+ return
+ try:
+ workflows.update_workflow_tags(workflow_id, tag_ids, **conn)
+ except requests.exceptions.RequestException:
+ # Not just HTTPError: a timeout or dropped connection here would otherwise
+ # escape and make the caller count an already-created workflow as failed,
+ # so a retry would duplicate it.
+ _diag(f"Could not restore tags on {workflow_id} — reattach them manually")
+
+
def _auto_snapshot(workflow_id: str, conn: dict[str, str], trigger: str) -> None:
"""Save a version snapshot before modifying a workflow."""
try:
@@ -320,8 +540,12 @@ def workflow_get(ctx: click.Context, workflow_id: str) -> None:
def workflow_create(ctx: click.Context, json_data: str) -> None:
"""Create a workflow from JSON (inline or @file.json). Workflows are created inactive."""
payload = _load_json_arg(json_data)
- payload.pop("active", None) # Never auto-activate on create
- data = workflows.create_workflow(payload, **_conn(ctx))
+ tags = payload.get("tags")
+ # A file produced by `export` carries state the endpoint refuses; reduce it here
+ # so hand-written and exported JSON both work. `active` is readOnly, so workflows
+ # are created inactive either way.
+ data = _create_workflow(_clean_for_api(payload), _conn(ctx))
+ _reapply_tags(data.get("id"), tags, _conn(ctx))
output(data, _json_flag(ctx))
@@ -333,8 +557,10 @@ def workflow_update(ctx: click.Context, workflow_id: str, json_data: str) -> Non
"""Update a workflow. Does not change active status — use activate/deactivate."""
_auto_snapshot(workflow_id, _conn(ctx), "update")
payload = _load_json_arg(json_data)
- payload.pop("active", None) # Don't change active status via update
- data = workflows.update_workflow(workflow_id, payload, **_conn(ctx))
+ # Same reduction as every other write: a file straight out of `export` has to be
+ # usable here. `active` is readOnly, so this cannot change it — use
+ # activate/deactivate. Tags likewise have their own command (`set-tags`).
+ data = _update_workflow(workflow_id, _clean_for_api(payload), _conn(ctx))
output(data, _json_flag(ctx))
@@ -411,8 +637,10 @@ def workflow_export(ctx: click.Context, workflow_id: str, out_path: str | None)
if not out_path:
name = _safe_filename(data.get("name", workflow_id))
out_path = f"{name}.json"
- # Remove server-specific fields for portability
- export_data = _clean_for_api(data)
+ # Remove server-specific fields for portability, but keep the state an export is
+ # expected to carry (`tags`, `active`). Reducing it to the writable set here would
+ # lose the tags, which `import` puts back through their own endpoint.
+ export_data = _strip_server_fields(data)
out = Path(out_path)
if out.exists():
warn(f"File {out_path} already exists — overwriting")
@@ -431,13 +659,14 @@ def workflow_import(ctx: click.Context, file_path: str, name: str | None) -> Non
if not isinstance(data, dict):
error("Invalid workflow format: must be a JSON object, not array or string")
return
- # Remove fields that would conflict on import
- for field in ("id", "createdAt", "updatedAt", "versionId", "shared"):
- data.pop(field, None)
- data["active"] = False # Never auto-activate imported workflows
+ # Keep only what n8n accepts. `active` is readOnly on the workflow endpoint, so
+ # it cannot be set here — workflows are created inactive regardless.
+ tags = data.get("tags")
+ data = _clean_for_api(data)
if name:
data["name"] = name
- result = workflows.create_workflow(data, **_conn(ctx))
+ result = _create_workflow(data, _conn(ctx))
+ _reapply_tags(result.get("id"), tags, _conn(ctx))
success(f"Imported as workflow {result.get('id', '?')} — {result.get('name', '?')}")
output(result, _json_flag(ctx))
@@ -475,7 +704,7 @@ def workflow_backup_all(ctx: click.Context, out_dir: str, active_only: bool) ->
wf_id = w.get("id", "unknown")
try:
full = workflows.get_workflow(wf_id, **conn)
- export_data = _clean_for_api(full)
+ export_data = _strip_server_fields(full)
name_safe = _safe_filename(full.get("name", wf_id))
filename = f"{wf_id}_{name_safe}.json"
(out_path / filename).write_text(json.dumps(export_data, indent=2, default=str))
@@ -522,10 +751,11 @@ def workflow_restore_all(ctx: click.Context, backup_dir: str, dry_run: bool) ->
click.echo(f" Would import: {name}")
ok += 1
continue
- for field in ("id", "createdAt", "updatedAt", "versionId", "shared"):
- data.pop(field, None)
- data["active"] = False # Never auto-activate restored workflows
- result = workflows.create_workflow(data, **conn)
+ # A backup keeps state the workflow endpoint refuses (`active`, `tags`);
+ # restore reduces it to the writable definition and puts the tags back
+ # through their own endpoint.
+ result = _create_workflow(_clean_for_api(data), conn)
+ _reapply_tags(result.get("id"), data.get("tags"), conn)
click.secho(f" {result.get('id', '?')} {name}", fg="green")
ok += 1
except Exception as exc:
@@ -557,7 +787,7 @@ def workflow_diff(ctx: click.Context, source: str, target: str) -> None:
return workflows.get_workflow(ref, **conn)
def _clean(data: dict) -> dict:
- return _clean_for_api(data)
+ return _strip_server_fields(data)
src = _clean(_load(source))
tgt = _clean(_load(target))
@@ -1038,16 +1268,16 @@ def template_deploy(ctx: click.Context, template_id: int, name: str | None) -> N
wf_wrapper = data.get("workflow", {})
wf_data = wf_wrapper.get("workflow", wf_wrapper) if isinstance(wf_wrapper, dict) else {}
- # Clean for import — never auto-activate
- for field in ("id", "createdAt", "updatedAt", "versionId", "shared"):
- wf_data.pop(field, None)
- wf_data["active"] = False
+ # Keep only what n8n accepts; `active` is readOnly, so a template always lands
+ # inactive. n8n.io templates often omit `settings`, which the API requires —
+ # _clean_for_api supplies it.
+ wf_data = _clean_for_api(wf_data)
if name:
wf_data["name"] = name
elif not wf_data.get("name"):
wf_data["name"] = f"Template #{template_id}"
- result = workflows.create_workflow(wf_data, **conn)
+ result = _create_workflow(wf_data, conn)
success(f"Deployed as workflow {result.get('id', '?')} — {result.get('name', '?')}")
output(result, _json_flag(ctx))
@@ -1193,7 +1423,7 @@ def workflow_autofix(ctx: click.Context, source: str, apply: bool, save_path: st
elif apply and wf_id:
_auto_snapshot(wf_id, conn, "autofix")
update_data = _clean_for_api(fixed_wf)
- workflows.update_workflow(wf_id, update_data, **conn)
+ _update_workflow(wf_id, update_data, conn)
success(f"Applied {len(fixes)} fix(es) to workflow {wf_id}")
elif apply and not wf_id:
error("Cannot apply fixes to a file source. Use --save instead.")
@@ -1310,7 +1540,7 @@ def workflow_patch(ctx: click.Context, workflow_id: str, rename: str | None, ena
_auto_snapshot(workflow_id, conn, "patch")
update_data = _clean_for_api(wf)
- result = workflows.update_workflow(workflow_id, update_data, **conn)
+ result = _update_workflow(workflow_id, update_data, conn)
output(result, _json_flag(ctx))
@@ -1455,7 +1685,8 @@ def versions_rollback(ctx: click.Context, workflow_id: str, ver_num: int | None)
pass # May already be inactive
update_data = _clean_for_api(snapshot)
update_data.pop("active", None)
- workflows.update_workflow(workflow_id, update_data, **conn)
+ _update_workflow(workflow_id, update_data, conn)
+ _reapply_tags(workflow_id, snapshot.get("tags"), conn)
success(f"Rolled back workflow {workflow_id} to version {ver_num} (deactivated — use activate to enable)")
@@ -1493,7 +1724,7 @@ def versions_diff(ctx: click.Context, workflow_id: str, version_a: int, version_
return
def _clean(d: dict) -> str:
- clean = {k: v for k, v in d.items() if k not in ("id", "createdAt", "updatedAt", "versionId", "shared")}
+ clean = _strip_server_fields(d)
return json.dumps(clean, indent=2, sort_keys=True, default=str)
lines_a = _clean(snap_a).splitlines(keepends=True)
@@ -1698,7 +1929,7 @@ def workflow_scaffold(ctx: click.Context, pattern: str, name: str | None, deploy
return
if deploy:
- result = workflows.create_workflow(wf, **_conn(ctx))
+ result = _create_workflow(_clean_for_api(wf), _conn(ctx))
success(f"Deployed '{wf['name']}' as workflow {result.get('id', '?')}")
output(result, _json_flag(ctx))
elif out_path:
diff --git a/n8n/agent-harness/cli_anything/n8n/tests/test_api_payload_fields.py b/n8n/agent-harness/cli_anything/n8n/tests/test_api_payload_fields.py
new file mode 100644
index 000000000..09f866542
--- /dev/null
+++ b/n8n/agent-harness/cli_anything/n8n/tests/test_api_payload_fields.py
@@ -0,0 +1,461 @@
+"""Payload shape for workflow writes.
+
+The n8n public API workflow schema sets `additionalProperties: false` and marks
+`active`, `tags`, `meta`, `isArchived`, `triggerCount` and the id/timestamp fields
+`readOnly`, so a create/update body carrying any of them is rejected outright with
+`400 - request/body must NOT have additional properties`.
+
+Every command that edits an existing workflow builds its payload from a GET
+response, so the payload has to be reduced first. These tests pin that reduction and
+keep it distinct from the local-only reduction used by backups and diffs, which has
+to preserve exactly the state the API refuses.
+
+No n8n instance required.
+"""
+
+import json
+from unittest.mock import patch
+
+import pytest
+import requests
+
+from cli_anything.n8n import n8n_cli
+from cli_anything.n8n.n8n_cli import _clean_for_api, _load_json_arg
+
+# Every key a GET /workflows/{id} returns on n8n 2.16.1, plus the two properties the
+# schema gained by 2.33.3 (`nodeGroups`, `parentFolderId`).
+SERVER_WORKFLOW = {
+ "id": "abc123",
+ "name": "Test WF",
+ "nodes": [{"type": "n8n-nodes-base.manualTrigger"}],
+ "connections": {},
+ "settings": {},
+ "staticData": {"lastId": 1},
+ "pinData": {"Test Node": [{"json": {"x": 1}}]},
+ "description": "a description",
+ "nodeGroups": [{"name": "group A"}],
+ "parentFolderId": "fld123",
+ "active": False,
+ "activeVersion": None,
+ "activeVersionId": None,
+ "isArchived": False,
+ "meta": {},
+ "tags": [],
+ "triggerCount": 0,
+ "versionCounter": 1,
+ "versionId": "v1",
+ "createdAt": "2026-01-01",
+ "updatedAt": "2026-01-02",
+ "shared": [{"role": "owner"}],
+}
+
+# readOnly in the schema, or absent from it entirely. Each one draws a 400.
+REJECTED_BY_API = (
+ "active",
+ "activeVersion",
+ "activeVersionId",
+ "isArchived",
+ "meta",
+ "tags",
+ "triggerCount",
+ "versionCounter",
+ "id",
+ "createdAt",
+ "updatedAt",
+ "versionId",
+)
+
+# Writable per the schema, and confirmed to persist by reading the workflow back.
+WRITABLE = (
+ "name",
+ "description",
+ "nodes",
+ "connections",
+ "settings",
+ "staticData",
+ "pinData",
+ "nodeGroups",
+ "parentFolderId",
+)
+
+
+def strip_server_fields(data):
+ """`_strip_server_fields` via the module, so upstream builds skip instead of erroring."""
+ fn = getattr(n8n_cli, "_strip_server_fields", None)
+ if fn is None:
+ pytest.skip("_strip_server_fields not present in this build")
+ return fn(data)
+
+
+# ─── Write payload ──────────────────────────────────────────────────────────
+
+class TestWritePayload:
+ def test_drops_every_field_the_api_rejects(self):
+ cleaned = _clean_for_api(SERVER_WORKFLOW)
+ leaked = [f for f in REJECTED_BY_API if f in cleaned]
+ assert not leaked, f"payload would be rejected by n8n, extra fields: {leaked}"
+
+ def test_keeps_writable_fields(self):
+ """Narrowing this further would silently discard user data.
+
+ pinData holds pinned sample data, staticData holds stateful-trigger cursors
+ and nodeGroups holds the canvas grouping — none of them survive an edit that
+ drops them, and none of them fail loudly.
+ """
+ cleaned = _clean_for_api(SERVER_WORKFLOW)
+ for field in WRITABLE:
+ assert field in cleaned, f"{field} must survive a workflow edit"
+
+ def test_drops_a_field_the_schema_does_not_define(self):
+ """A key from a future n8n release must not reach the API by default.
+
+ This is what a blacklist cannot do: it only removes what it already knows.
+ """
+ cleaned = _clean_for_api({**SERVER_WORKFLOW, "someFieldAddedLater": "x"})
+ assert "someFieldAddedLater" not in cleaned
+
+ def test_drops_nulls_for_non_nullable_properties(self):
+ """`description` is a plain string in the schema, so a null round-trip 400s.
+
+ A workflow with no description reads back as `"description": null`, which is
+ exactly what a backup or an export then tries to send.
+ """
+ cleaned = _clean_for_api({**SERVER_WORKFLOW, "description": None})
+ assert "description" not in cleaned
+
+ def test_keeps_nulls_for_nullable_properties(self):
+ """For these, null is the only way to clear the value — dropping it is a bug.
+
+ `versions rollback` restores a snapshot: one taken before any pinned data was
+ added carries `pinData: null`, and omitting that key would leave today's
+ pinned data in place while the command reports a successful rollback.
+ """
+ cleaned = _clean_for_api(
+ {**SERVER_WORKFLOW, "pinData": None, "staticData": None, "parentFolderId": None}
+ )
+ assert cleaned["pinData"] is None
+ assert cleaned["staticData"] is None
+ assert cleaned["parentFolderId"] is None # documented as "move to the project root"
+
+ def test_always_supplies_the_required_settings_object(self):
+ """`settings` is required by the schema; handwritten and older exports omit it."""
+ wf = {k: v for k, v in SERVER_WORKFLOW.items() if k != "settings"}
+ assert _clean_for_api(wf)["settings"] == {}
+ assert _clean_for_api({**SERVER_WORKFLOW, "settings": None})["settings"] == {}
+
+ def test_leaves_a_non_object_settings_for_the_server_to_reject(self):
+ """Replacing it with `{}` would drop what the caller wrote without saying so.
+
+ `settings` has to be an object, so a string or a list is invalid input — but
+ that is the server's verdict to give, by name.
+ """
+ for bad in ("nope", [1], 5):
+ assert _clean_for_api({**SERVER_WORKFLOW, "settings": bad})["settings"] == bad
+
+ def test_reduces_the_nested_settings_object_too(self):
+ """The nested object is additionalProperties:false as well, so an unreduced
+ settings block fails the request even when the top level is clean."""
+ wf = {**SERVER_WORKFLOW, "settings": {"executionOrder": "v1", "notASetting": 1}}
+ assert _clean_for_api(wf)["settings"] == {"executionOrder": "v1"}
+
+ def test_keeps_settings_that_only_newer_schemas_define(self):
+ """`binaryMode` is written into every workflow by the editor and became
+ writable in 2.33.3, so stripping it here would reset the user's choice on a
+ current instance. An older instance rejects it, and the cross-version retry
+ is what drops it — at the cost of one failed request, which beats silently
+ changing a setting.
+ """
+ wf = {**SERVER_WORKFLOW, "settings": {"executionOrder": "v1", "binaryMode": "separate"}}
+ assert _clean_for_api(wf)["settings"]["binaryMode"] == "separate"
+
+ def test_drops_shared_even_though_the_api_tolerates_it(self):
+ """`shared` is ownership data, not part of the definition.
+
+ Unlike the rejected fields it does not draw a 400 — the API answers 200 and
+ ignores it (confirmed by reading the workflow back afterwards). That is
+ precisely why it needs pinning here: a failing request would not catch it.
+ """
+ assert "shared" not in _clean_for_api(SERVER_WORKFLOW)
+
+ def test_export_output_can_be_fed_back_to_update(self, tmp_path):
+ """Helper-level stand-in for `workflow export` -> `workflow update @file.json`.
+
+ It repeats what those two commands do to the payload rather than invoking
+ them, so it pins the reduction, not the click plumbing.
+ """
+ exported = strip_server_fields(SERVER_WORKFLOW) # what workflow_export writes
+ out = tmp_path / "export.json"
+ out.write_text(json.dumps(exported, indent=2))
+
+ payload = _clean_for_api(_load_json_arg(f"@{out}")) # what workflow_update sends
+ leaked = [f for f in REJECTED_BY_API if f in payload]
+ assert not leaked, f"export cannot be fed back into update, extra fields: {leaked}"
+
+
+# ─── Local-only payload ─────────────────────────────────────────────────────
+
+class TestLocalPayload:
+ def test_backup_keeps_state_the_api_refuses(self):
+ """A backup that drops `active`/`tags` cannot restore what it recorded."""
+ kept = strip_server_fields(SERVER_WORKFLOW)
+ for field in ("active", "tags", "isArchived"):
+ assert field in kept, f"{field} must stay in a backup"
+
+ def test_backup_drops_instance_specific_fields(self):
+ kept = strip_server_fields(SERVER_WORKFLOW)
+ for field in ("id", "createdAt", "updatedAt", "versionId", "shared"):
+ assert field not in kept
+
+ def test_diff_can_still_see_a_state_only_change(self):
+ """Two workflows differing only in `active` must not compare as identical."""
+ a = {**SERVER_WORKFLOW, "active": False}
+ b = {**SERVER_WORKFLOW, "active": True}
+ assert strip_server_fields(a) != strip_server_fields(b)
+
+
+# ─── Tag reassignment ───────────────────────────────────────────────────────
+
+class TestReapplyTags:
+ """`tags` is readOnly on the workflow body and has its own endpoint.
+
+ Anything that recreates or rewinds a workflow therefore loses its tags unless
+ they are set separately — and loses them *silently*, since the create itself
+ succeeds.
+ """
+
+ @staticmethod
+ def _reapply():
+ fn = getattr(n8n_cli, "_reapply_tags", None)
+ if fn is None:
+ pytest.skip("_reapply_tags not present in this build")
+ return fn
+
+ def test_leaves_tags_alone_when_the_source_recorded_none(self):
+ """An older export has no `tags` key at all — that is not "clear the tags"."""
+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:
+ self._reapply()("wf1", None, {})
+ mock_put.assert_not_called()
+
+ def test_clears_tags_when_the_source_had_an_empty_list(self):
+ """Rolling back to a snapshot taken before any tag existed must remove them."""
+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:
+ self._reapply()("wf1", [], {})
+ mock_put.assert_called_once_with("wf1", [])
+
+ def test_sends_only_ids(self):
+ """A backup records the whole tag object; the endpoint takes ids."""
+ tags = [{"id": "t1", "name": "prod", "createdAt": "2026-01-01"}, {"name": "no id"}]
+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:
+ self._reapply()("wf1", tags, {})
+ mock_put.assert_called_once_with("wf1", [{"id": "t1"}])
+
+ def test_leaves_tags_alone_when_none_of_them_carry_an_id(self):
+ """An unreadable record must not be treated as "the source had no tags".
+
+ Filtering the ids out of a non-empty list yields an empty list, and sending
+ that would clear every tag on the workflow.
+ """
+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:
+ self._reapply()("wf1", [{"name": "prod"}, {"nope": 1}], {})
+ mock_put.assert_not_called()
+
+ def test_survives_a_tags_value_that_is_not_a_list(self):
+ """A scalar would raise on iteration — after the workflow already exists.
+
+ The caller would then report a failure for something that was created, and
+ a `restore-all` retry would duplicate it.
+ """
+ for bad in (1, 1.5, True):
+ with patch.object(n8n_cli.workflows, "update_workflow_tags") as mock_put:
+ self._reapply()("wf1", bad, {}) # must not raise
+ mock_put.assert_not_called()
+
+ def test_survives_a_timeout_not_just_an_http_error(self):
+ """The workflow is already created; a tag timeout must not fail the caller.
+
+ `restore-all` would otherwise count the file as failed and a retry would
+ create a duplicate workflow.
+ """
+ for err in (requests.exceptions.Timeout(), requests.exceptions.ConnectionError()):
+ with patch.object(n8n_cli.workflows, "update_workflow_tags", side_effect=err):
+ self._reapply()("wf1", [{"id": "t1"}], {}) # must not raise
+
+ def test_reports_but_does_not_raise_when_the_ids_are_unknown(self):
+ """Restoring into a different instance answers 404 Some tags not found.
+
+ The workflow itself is already created at that point, so failing the whole
+ restore over its tags would lose more than it protects.
+ """
+ err = requests.exceptions.HTTPError("404 Some tags not found")
+ with patch.object(n8n_cli.workflows, "update_workflow_tags", side_effect=err):
+ self._reapply()("wf1", [{"id": "gone"}], {}) # must not raise
+
+ def test_export_keeps_tags_so_import_can_restore_them(self):
+ """`export` writes the local form; the tags are what `import` reattaches.
+
+ Reducing the export to the writable set instead would drop them silently —
+ the file would still import, just without its tags.
+ """
+ exported = strip_server_fields({**SERVER_WORKFLOW, "tags": [{"id": "t1", "name": "prod"}]})
+ assert exported["tags"] == [{"id": "t1", "name": "prod"}]
+
+
+# ─── Cross-version writes ───────────────────────────────────────────────────
+
+class TestNewerSchemaFallback:
+ """A file exported from n8n 2.33.3+ has to remain importable into an older one.
+
+ `nodeGroups` and `parentFolderId` do not exist in the older schema, whose
+ additionalProperties:false rejects the whole request.
+ """
+
+ @staticmethod
+ def _send():
+ fn = getattr(n8n_cli, "_send_workflow", None)
+ if fn is None:
+ pytest.skip("_send_workflow not present in this build")
+ return fn
+
+ @staticmethod
+ def _http_error(status, message="request/body must NOT have additional properties"):
+ resp = type("R", (), {"status_code": status, "json": lambda self: {"message": message}})()
+ return requests.exceptions.HTTPError(response=resp)
+
+ def test_retries_without_the_newer_properties(self):
+ seen = []
+
+ def send(body):
+ seen.append(dict(body))
+ if "nodeGroups" in body:
+ raise self._http_error(400)
+ return {"id": "wf1"}
+
+ payload = {"name": "x", "nodes": [], "nodeGroups": [{"name": "g"}], "parentFolderId": "f1"}
+ assert self._send()(send, payload) == {"id": "wf1"}
+ assert len(seen) == 2
+ assert "nodeGroups" not in seen[1] and "parentFolderId" not in seen[1]
+ assert seen[1]["name"] == "x" # everything else survives
+
+ def test_also_strips_newer_properties_nested_in_settings(self):
+ """`settings` is additionalProperties:false too — dropping only the outer
+ ones would retry and fail on the same request."""
+ seen = []
+
+ def send(body):
+ seen.append({**body, "settings": dict(body.get("settings", {}))})
+ if "binaryMode" in body.get("settings", {}):
+ raise self._http_error(400)
+ return {"id": "wf1"}
+
+ payload = {
+ "name": "x",
+ "nodes": [],
+ "settings": {"executionOrder": "v1", "binaryMode": "separate"},
+ }
+ assert self._send()(send, payload) == {"id": "wf1"}
+ assert len(seen) == 2
+ assert seen[1]["settings"] == {"executionOrder": "v1"}
+
+ def test_does_not_retry_when_the_payload_has_none_of_them(self):
+ """A 400 about something else must surface, not be masked by a pointless retry."""
+ calls = []
+
+ def send(body):
+ calls.append(body)
+ raise self._http_error(400)
+
+ with pytest.raises(requests.exceptions.HTTPError):
+ self._send()(send, {"name": "x", "nodes": []})
+ assert len(calls) == 1
+
+ def test_does_not_retry_on_other_status_codes(self):
+ def send(body):
+ raise self._http_error(401)
+
+ with pytest.raises(requests.exceptions.HTTPError):
+ self._send()(send, {"name": "x", "nodeGroups": []})
+
+ def test_does_not_retry_when_the_400_is_about_a_bad_value(self):
+ """A rejected *value* must surface, not be silenced by dropping the property.
+
+ n8n answers `must be number` / `must be string` for these, as opposed to
+ `must NOT have additional properties`. Retrying without the property would
+ drop configuration the caller asked for and then report success — which is
+ worse than the original failure, because it looks like it worked.
+ """
+ calls = []
+
+ def send(body):
+ calls.append(body)
+ raise self._http_error(400, "request/body/settings/executionTimeout must be number")
+
+ payload = {"name": "x", "nodes": [], "nodeGroups": [{"name": "g"}]}
+ with pytest.raises(requests.exceptions.HTTPError):
+ self._send()(send, payload)
+ assert len(calls) == 1, "a bad value must not trigger the compatibility retry"
+
+ def test_does_not_retry_when_the_offending_property_is_nested_deeper(self):
+ """Same wording, different meaning: this is malformed input, not a version gap.
+
+ A grouping whose item carries an unexpected member reports
+ `request/body/nodeGroups/0 must NOT have additional properties`. Treating
+ that as a compatibility problem would drop the entire grouping and could
+ then succeed — turning invalid input into a success that lost data.
+ """
+ for path in ("request/body/nodeGroups/0", "request/body/nodes/0"):
+ calls = []
+
+ def send(body):
+ calls.append(body)
+ raise self._http_error(400, f"{path} must NOT have additional properties")
+
+ with pytest.raises(requests.exceptions.HTTPError):
+ self._send()(send, {"name": "x", "nodeGroups": [{"name": "g", "bogus": 1}]})
+ assert len(calls) == 1, f"{path} must not trigger the compatibility retry"
+
+ def test_retries_for_both_reducible_paths(self):
+ """The two levels the retry actually reduces."""
+ for path in ("request/body", "request/body/settings"):
+ calls = []
+
+ def send(body):
+ calls.append(body)
+ if len(calls) == 1:
+ raise self._http_error(400, f"{path} must NOT have additional properties")
+ return {"id": "wf1"}
+
+ payload = {"name": "x", "nodeGroups": [], "settings": {"binaryMode": "separate"}}
+ assert self._send()(send, payload) == {"id": "wf1"}
+ assert len(calls) == 2
+
+ def test_does_not_retry_when_the_error_body_is_unreadable(self):
+ """No message to inspect means no evidence for a compatibility problem."""
+ resp = type("R", (), {"status_code": 400, "json": lambda self: (_ for _ in ()).throw(ValueError())})()
+ calls = []
+
+ def send(body):
+ calls.append(body)
+ raise requests.exceptions.HTTPError(response=resp)
+
+ with pytest.raises(requests.exceptions.HTTPError):
+ self._send()(send, {"name": "x", "nodeGroups": []})
+ assert len(calls) == 1
+
+
+
+# ─── Diagnostics ────────────────────────────────────────────────────────────
+
+class TestDiagnosticsStream:
+ def test_fallback_diagnostics_go_to_stderr(self, capsys):
+ """`--json` output has to stay parseable when a fallback fires.
+
+ `warn()` prints to stdout, so the diagnostics on these paths deliberately
+ do not use it.
+ """
+ diag = getattr(n8n_cli, "_diag", None)
+ if diag is None:
+ pytest.skip("_diag not present in this build")
+ diag("something happened")
+ captured = capsys.readouterr()
+ assert captured.out == ""
+ assert "something happened" in captured.err