n8n API Version Mismatch Errors

Step by Step Guide to solve n8n API Version Mismatch Error

 

 

---

 

Who this is for: n8n administrators, workflow engineers, and developers maintaining custom nodes or external integrations. We cover this in detail in the n8n API Integration Errors Guide.

Quick Diagnosis

The API version mismatch error appears when a workflow or custom node calls an outdated n8n endpoint (e.g., v1 instead of the current v2). Fix it in three steps:

1. Check the active API version – Settings → API or n8n config get apiVersion.
2. Update every request URL in your workflows to the correct version (/api/v2/…).
3. Restart n8n (or reload the workflow) to apply the change.

Result: the endpoint returns 200 OK instead of 400/404 version‑mismatch errors.

1. Why n8n Enforces API Versioning

If you encounter any n8n connection timeout settings resolve them before continuing with the setup.

Reason	What Happens If Ignored
Backward‑compatibility – n8n may deprecate fields or change response shapes between versions.	Requests hit the wrong router, returning VersionMismatchError: Expected v2, got v1.
Security & rate‑limiting – each version can have its own auth schema.	Tokens generated for v1 are rejected by v2 endpoints.
Feature gating – new node parameters are only exposed in the latest version.	Workflows silently skip new functionality, causing silent data loss.

EEFA Note: In production, never rely on the default “latest” fallback. Explicitly version every endpoint to avoid accidental breakage when n8n auto‑updates.

2. Detecting the Mismatch – Where the Error Shows Up

If you encounter any n8n legacy node deprecation errors resolve them before continuing with the setup.

Context	Typical Error Message	Where to Find It
Workflow execution log	Error: API version mismatch – expected v2, received v1	*Execution → Logs* panel
Custom node (JavaScript)	throw new Error('VersionMismatchError: v1 ≠ v2')	Console output or n8n.log
HTTP Request node	400 Bad Request – version mismatch	Response body / header x-n8n-api-version

Quick test – Verify the version served by the endpoint with curl:

curl -i -X GET http://localhost:5678/api/v1/workflows

*If you receive 200 OK, the instance still serves v1 (rare on recent releases).

3. Step‑by‑Step Fix Guide

3.1 Verify the Current API Version

Run the CLI command below; it prints the version that n8n expects.

# Using the n8n CLI
n8n config get apiVersion
# Example output: "v2"

If the output is v1, upgrade your n8n instance before proceeding.

3.2 Locate All Versioned URLs in the Workspace

Database search (PostgreSQL example) – finds workflows that still reference /api/v1/:

SELECT id, name FROM workflow WHERE data::text ILIKE '%/api/v1/%';

Filesystem search – catches custom nodes or external scripts.

grep -R "/api/v1/" ./workflows ./custom-nodes

3.3 Update URLs to the Correct Version

Replace each legacy segment (/api/v1/) with the version you confirmed in 3.1 (/api/v2/). Example for an **HTTP Request node**:

Before (v1)	After (v2)
https://my-n8n-instance.com/api/v1/trigger	https://my-n8n-instance.com/api/v2/trigger
{{ $json[“url”] }}/api/v1/webhook	{{ $json[“url”] }}/api/v2/webhook

Best practice: store the version in an environment variable and reference it ({{$env.API_VERSION}}). This centralises the string and prevents future mismatches.

3.4 Refresh Authentication Tokens (if needed)

Some endpoints bind the token to a specific version. Regenerate the token after the URL change:

# UI → Settings → API → Generate New Key
# Or via CLI:
n8n api-key:create --name "migration-key"

3.5 Restart / Reload

Deployment method	Command
Docker	docker restart n8n
PM2	pm2 restart n8n
Standalone binary	Stop the process and start it again

3.6 Validate the Fix

Re‑run the workflow or query the endpoint directly:

curl -i -X GET http://localhost:5678/api/v2/workflows

A 200 response with a JSON payload confirms the version mismatch is resolved.

If the error persists, move to the troubleshooting checklist.

4. Troubleshooting Checklist

Done	Item
☐	Confirm n8n config get apiVersion matches the version you updated to.
☐	Search all workflow JSON for legacy /api/v1/ strings.
☐	Verify external scripts (GitHub Actions, CI pipelines) use the new version.
☐	Regenerate API keys/tokens after URL change.
☐	Restart every n8n instance (in a clustered setup, all nodes).
☐	Check the n8n logs (~/.n8n/logs/*.log) for lingering VersionMismatchError.
☐	If using a reverse proxy (NGINX, Traefik), ensure it forwards the new path correctly.
☐	Confirm no custom middleware intercepts /api/v1/ and rewrites it.

EEFA Warning: In a high‑availability cluster, updating only one node can cause inter‑node version conflicts, leading to intermittent failures. Apply the version change uniformly across the cluster before restarting any node.

5. Advanced: Managing Multiple API Versions in the Same Environment

When a short‑term migration window requires both legacy and current endpoints:

1. Enable the legacy router (self‑hosted only):

   n8n config set enableLegacyApi true
   

2. Scope the version per request with a custom header:

   X-n8n-Api-Version: v1   # or v2
   

3. Create a version‑aware custom node that reads {{$env.API_VERSION}} and builds the URL dynamically.

EEFA Caveat: Legacy mode disables some security hardening checks. Use it only temporarily and monitor security.log for suspicious activity.

6. Real‑World Example – Migrating a Google Sheets Trigger

Before (v1) – raw JSON snippet

{
  "type": "n8n-nodes-base.googleSheets",
  "parameters": {
    "operation": "watch",
    "sheetId": "1a2b3c",
    "range": "A1:C10",
    "url": "https://my-n8n.com/api/v1/webhook/123"
  }
}

After (v2) – raw JSON snippet

{
  "type": "n8n-nodes-base.googleSheets",
  "parameters": {
    "operation": "watch",
    "sheetId": "1a2b3c",
    "range": "A1:C10",
    "url": "https://my-n8n.com/api/v2/webhook/123"
  }
}

What we did

1. Ran the DB search query to locate the old URL.
2. Updated the node JSON via the UI’s Edit → Raw JSON view.
3. Regenerated the webhook secret (n8n auto‑rotates on version change).
4. Restarted the Docker container.

Result: the Google Sheets trigger fired without a version‑mismatch error.

8. Next Steps

• Automating version checks – add a pre‑deployment script that scans for /api/v1/ strings.
• Monitoring deprecation – configure a Grafana alert on the n8n_version_mismatch_total metric (if you expose Prometheus).
• Cluster‑wide migration – read the n8n HA upgrade guide to coordinate version updates across multiple nodes.

Keep your n8n instance on the latest API version to guarantee compatibility, security, and access to new node features.