fix(workflow-diff): roll back to prior state when n8n PUT fails post-save (czlonkowski#769)

* fix(workflow-diff): roll back to prior state when n8n PUT fails post-save

When n8n_update_partial_workflow's underlying PUT fails (e.g. n8n persisted
the workflow body but the activation step within the same PUT then tripped
on an unsupported typeVersion), the workflow was being left in a broken
state. The handler already snapshots the prior workflow into workflowBefore
for telemetry, so we piggyback on it: on PUT failure, attempt a rollback
PUT to restore the prior state.

Three return paths on failure:
- Pre-mutation (no snapshot, e.g. validateOnly) — preserve current behaviour
- Rollback succeeded — error suffixed with "(workflow restored to prior
  state)" + details.rollbackPerformed = true
- Rollback failed — composite error pointing to n8n_workflow_versions for
  manual recovery + details.rollbackPerformed = false + rollbackError

Success path is byte-identical to before.

Tests:
- New "should roll back to prior state when n8n PUT fails after persisting
  body" test asserts the rollback PUT fires with the prior snapshot
- New "should report rollback failure when both PUTs fail" test asserts
  the composite error is surfaced
- Existing "should not attempt rollback in validateOnly mode" remains intact

Known limitations (documented in PR description):
- Concurrent writers can race the rollback. Same race window as today's
  plain PUT. A future iteration could use versionId for optimistic
  concurrency.
- Rollback fires even when n8n rejected pre-save (body never persisted).
  Rollback is a no-op in that case — one extra HTTP request on the
  failure path. Chose this over guessing n8n's error semantics.

* fix(workflow-diff): skip rollback on pre-save rejection + actionable recovery

Building on the rollback-on-error fix, distinguish two failure modes via a
post-failure GET that compares versionId / versionCounter / updatedAt
against the snapshot:

- Persist-then-fail (n8n saved the body before activation died): roll back
  by re-PUTting the prior snapshot. Error gets the existing
  "(workflow restored to prior state)" suffix.
- Pre-save rejection (body never persisted): skip the rollback PUT — it
  would be wasted and the suffix would mislead the caller.
  details.rollbackPerformed: false; no suffix.

When rollback fails, surface workflowBefore.versionId as
details.priorVersionId so callers can recover via n8n_workflow_versions.

The version comparison is tri-state (same / changed / unknown). On
"unknown" — older n8n versions that omit all three fields, or a failing
post-failure GET — fall back to attempting rollback. The silent-corruption
class from czlonkowski#770 is far worse than a redundant PUT.

Tests cover persist-then-fail rollback, pre-save no-rollback, GET-failure
best-effort rollback, versionCounter-only fallback, no-version-fields
safety net, and double-PUT-failure with priorVersionId. 45/45 in
handlers-workflow-diff.test.ts; 611/611 across tests/unit/mcp.

Bumped to v2.50.3.

Author: pybe

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.50.3] - 2026-05-04
+
+### Fixed
+
+- `n8n_update_partial_workflow` now rolls back the prior workflow snapshot when n8n persists a body before failing (e.g. unsupported `typeVersion` trips the activation step inside the same PUT), preventing silent corruption of active workflows. Reported and originally fixed by @pybe (#769, closes #770).
+- The rollback no longer fires (and no longer claims `(workflow restored to prior state)`) when n8n rejected the PUT before persisting. The handler now compares `versionId` / `versionCounter` / `updatedAt` from a fresh GET to detect whether persistence actually happened.
+- Rollback-failure responses include `details.priorVersionId` so callers can recover the right snapshot via `n8n_workflow_versions`.
+
+Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en
+
 ## [2.50.2] - 2026-05-04
 
 ### Security

dist/mcp/handlers-workflow-diff.d.ts.map

@@ -1,6 +1,6 @@
 {
   "name": "n8n-mcp",
-  "version": "2.50.2",
+  "version": "2.50.3",
   "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

dist/mcp/handlers-workflow-diff.js

@@ -21,6 +21,28 @@ import { EnhancedConfigValidator } from '../services/enhanced-config-validator';
 // Cached validator instance to avoid recreating on every mutation
 let cachedValidator: WorkflowValidator | null = null;
 
+// Detect whether a fetched workflow has moved past the snapshot we hold.
+// Tries versionId first (most reliable), then versionCounter (n8n 1.118.1+),
+// then updatedAt. Returns 'unknown' when no comparable field is present on
+// both sides; caller falls back to attempting rollback so the safety net
+// is preserved on older n8n versions.
+type VersionCompare = 'same' | 'changed' | 'unknown';
+function compareVersions(
+  a: { versionId?: string; versionCounter?: number; updatedAt?: string },
+  b: { versionId?: string; versionCounter?: number; updatedAt?: string },
+): VersionCompare {
+  if (a.versionId !== undefined && b.versionId !== undefined) {
+    return a.versionId === b.versionId ? 'same' : 'changed';
+  }
+  if (a.versionCounter !== undefined && b.versionCounter !== undefined) {
+    return a.versionCounter === b.versionCounter ? 'same' : 'changed';
+  }
+  if (a.updatedAt !== undefined && b.updatedAt !== undefined) {
+    return a.updatedAt === b.updatedAt ? 'same' : 'changed';
+  }
+  return 'unknown';
+}
+
 /**
  * Get or create cached workflow validator instance
  * Reuses the same validator to avoid redundant NodeSimilarityService initialization
@@ -325,7 +347,100 @@ export async function handleUpdatePartialWorkflow(
 
     // Update workflow via API
     try {
-      const updatedWorkflow = await client.updateWorkflow(input.id, diffResult.workflow!);
+      // Rollback-on-error: if the PUT fails, n8n may have persisted the body
+      // before failing (e.g. an unsupported typeVersion trips the activation
+      // step within the same PUT, but the body is already saved). Re-PUT the
+      // workflowBefore snapshot in that case to restore prior state. The
+      // snapshot is captured earlier in this handler for telemetry and is
+      // safe to reuse here.
+      //
+      // To distinguish persist-then-fail from pre-save rejection, GET the
+      // server state after the failed PUT and compare versionId (or
+      // versionCounter / updatedAt — whichever the running n8n exposes). If
+      // unchanged, the body never persisted and rolling back would be both
+      // a wasted PUT and a misleading "(restored to prior state)" message.
+      let updatedWorkflow;
+      try {
+        updatedWorkflow = await client.updateWorkflow(input.id, diffResult.workflow!);
+      } catch (updateError) {
+        if (workflowBefore && !input.validateOnly) {
+          let serverState: any = null;
+          try {
+            serverState = await client.getWorkflow(input.id);
+          } catch (getErr) {
+            logger.debug('Post-failure GET failed; falling back to best-effort rollback', getErr);
+          }
+          // Only skip rollback when we KNOW the body never persisted.
+          // If serverState is missing or we can't compare versions, attempt
+          // rollback as a safety net — the bug class in #770 is silent
+          // corruption, and a redundant PUT is far less harmful than a
+          // missed rollback.
+          const versionState = serverState
+            ? compareVersions(serverState, workflowBefore)
+            : 'unknown';
+
+          if (versionState === 'same') {
+            // Pre-save rejection: nothing to roll back.
+            logger.debug('PUT failed before persisting; skipping rollback', {
+              workflowId: input.id,
+            });
+            if (updateError instanceof N8nApiError) {
+              throw new N8nApiError(
+                updateError.message,
+                updateError.statusCode,
+                updateError.code,
+                {
+                  ...((updateError.details as Record<string, unknown>) ?? {}),
+                  rollbackPerformed: false,
+                },
+              );
+            }
+            throw updateError;
+          }
+
+          // Either persist-then-fail OR couldn't determine — attempt rollback.
+          let rollbackPerformed = false;
+          let rollbackErrorMessage: string | undefined;
+          try {
+            await client.updateWorkflow(input.id, workflowBefore);
+            rollbackPerformed = true;
+            logger.warn('updateWorkflow failed; rolled back to prior state', {
+              workflowId: input.id,
+              originalError: updateError instanceof Error ? updateError.message : String(updateError),
+            });
+          } catch (rollbackErr) {
+            rollbackErrorMessage = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+            logger.error('updateWorkflow failed AND rollback failed', {
+              workflowId: input.id,
+              originalError: updateError instanceof Error ? updateError.message : String(updateError),
+              rollbackError: rollbackErrorMessage,
+            });
+          }
+
+          // Re-throw with rollback context attached so the outer N8nApiError
+          // catch (below) surfaces it with the user-friendly formatting.
+          if (updateError instanceof N8nApiError) {
+            const augmentedDetails: Record<string, unknown> = {
+              ...((updateError.details as Record<string, unknown>) ?? {}),
+              rollbackPerformed,
+              ...(rollbackErrorMessage ? { rollbackError: rollbackErrorMessage } : {}),
+              ...(workflowBefore.versionId ? { priorVersionId: workflowBefore.versionId } : {}),
+            };
+            const suffix = rollbackPerformed
+              ? ' (workflow restored to prior state)'
+              : (rollbackErrorMessage
+                  ? ' (rollback also failed; workflow may be in a broken state — try n8n_workflow_versions for a backup)'
+                  : '');
+            throw new N8nApiError(
+              `${updateError.message}${suffix}`,
+              updateError.statusCode,
+              updateError.code,
+              augmentedDetails,
+            );
+          }
+        }
+        throw updateError;
+      }
 
       // Handle tag operations via dedicated API (#599)
       let tagWarnings: string[] = [];