Production diagnostic

Generate a handoff-ready n8n diagnostic brief.

Use this static form when a workflow blocks a real process and you need clean context for your team, vendor support, or your own incident notes. Nothing is submitted or stored.

Open checklist Use generator

What To Collect

The exact error message or failed execution link.
n8n version, hosting type, and whether it is Cloud or self-hosted.
Docker Compose or bare metal, database type, queue mode, Redis, and worker count when relevant.
The public URL and WEBHOOK_URL shape, with secrets and private hostnames removed.
Whether the workflow fails in test mode, production mode, queue worker, or all paths.
The last config, workflow, credential, or infrastructure change before the failure.
The business impact: what is blocked, who is waiting, and how urgent it is.
What you already tested, what changed after each test, and which diagnostic branch should be checked next.

Issue-specific evidence

Collect the proof that changes the next decision.

Use generator

queue

Queue mode / worker evidence

Capture proof that main, workers, Redis, Postgres, binary storage, and runner paths are aligned before changing concurrency.

Main and worker n8n image tags match.
Worker logs show whether jobs are picked up or reconnecting.
Redis PONG works from the worker network.
Queue mode, Redis host, DB_TYPE, binary data mode, and runner mode match.
N8N_ENCRYPTION_KEY and runner token parity are confirmed privately, without printing raw secrets.
One safe production execution moves from waiting to completed on a worker.

Queue mode setup Worker jobs checklist Official n8n queue docs

webhook

Webhook routing evidence

Prove whether the request reaches n8n, which URL mode is used, and whether proxy routing preserves method, path, and body.

Exact test URL and production URL, with tokens removed.
Workflow active state and Webhook node HTTP method.
External status code and response body.
Proxy or Cloudflare access log line at the same timestamp.
n8n execution exists or does not exist for that request.

Webhook troubleshooting Webhook 404

docker

Docker deployment evidence

Separate n8n app failure from persistence, public URL, database, proxy, and restore-path problems.

Exact image tag, not a floating latest assumption.
Compose service status and recent non-secret logs.
Persistent volume or Postgres backup proof.
WEBHOOK_URL and public URL shape, with private hosts removed.
One restart smoke test that preserves workflows and credentials.

Docker Compose checklist Volume persistence

postgres

Postgres connection evidence

Show whether the failing database is n8n's internal database or a workflow target, then prove network, SSL, auth, and permissions.

Internal n8n DB settings are separated from Postgres node credentials.
Host, port, database name, SSL mode, and least-privilege user are known.
A low-risk SELECT 1 or read-only query result is captured.
Queue workers can reach the same target when queue mode is enabled.

Postgres connection error Postgres setup

expression

Expression / JSON evidence

Capture the live item shape and failing path before rewriting nodes or guessing which field is missing.

Exact expression, node name, and failed item index.
Input JSON shape with secrets and customer data removed.
Whether the field is missing, null, array-shaped, or from a different branch.
A safe fallback expression or Set node check to verify the fix.

Expression error Invalid JSON

sheets

Google Sheets row evidence

Prove the credential, spreadsheet, tab, header row, mapping mode, and duplicate key before changing append/update behavior.

Credential account can open and edit the target spreadsheet.
Spreadsheet ID, tab name, and header row are copied from the current production sheet.
Previous node JSON keys match the intended sheet headers.
Append Row vs Append or Update Row is chosen intentionally.
Matching column is unique, non-blank, and stable across retries.
Two synthetic production-shaped runs create the intended one-row or two-row result.

Google Sheets node Gmail to Sheets workflow Official n8n Sheets docs

gmail

Gmail credential / trigger evidence

Prove the mailbox, credential path, label/message IDs, trigger filters, and safe-send boundary before broadening scopes or polling.

Credential type is known: OAuth2 or service account.
Gmail API access, scopes, impersonation, or domain-wide delegation are checked for 401/Forbidden errors.
Message ID, thread ID, and label ID are captured from the same mailbox and credential.
Trigger label, sender, search query, and read-status filters are recorded.
One controlled test message creates the expected execution or safe send.
Customer addresses, message bodies, OAuth tokens, and private mailbox IDs are redacted.

Gmail node Gmail to Sheets workflow Official n8n Gmail docs

Static brief generator

Fill the fields you know.

The generated brief stays in your browser. Remove secrets before sharing it with anyone.

Need a starting point?

Generated Brief

n8n issue:

Version:

Hosting type:

Database / queue / Redis:

Public URL and WEBHOOK_URL:

Where it happens:

Business impact:

Expected vs actual behavior:

Reproduction steps:

Recent changes:

What I already checked:

Logs or error message:

Next recommended branch:

Nothing is sent anywhere. Copy the brief when it is ready.

When This Is Ready For A Tool Decision

A production issue is ready for a tool or hosting decision when the failure is reproducible, the affected workflow is identified, secrets are removed, logs are attached, and the success condition is specific enough to verify after the fix.

Good First Fix Pages

Why This Exists

Most n8n troubleshooting gets slower when the first message is vague. A clean brief makes the problem reproducible, separates symptoms from assumptions, and keeps production changes easier to review.