n8n Debugger

AI-native debugging toolkit for n8n workflows. Works for both self-hosted and cloud n8n instances.

> Note: This is a third-party debugging tool, not affiliated with n8n.io. For official n8n CLI commands, see n8n CLI documentation.

Installation

``bash
npm install -g @seibert/n8n-debugger
`

Setup

`bash


Create a project directory

mkdir my-n8n-project && cd my-n8n-project

Initialize (creates .env template and copies agent guidelines)

n8n-debug init

Edit .env with your credentials, then test

n8n-debug list
`

The tool creates workflows/ and executions/ directories in your current working directory.

AI Agent Mode

Designed for autonomous AI debugging. When you describe a workflow problem to an AI assistant, it can:

1. Search for workflows by name
2. Check health and assess error patterns
3. Analyze recent errors with structured data
4. Pull and edit workflow JSON to fix issues
5. Validate and push changes back to n8n
6. Retry failed executions to verify fixes
7. Manage workflows (activate/deactivate, compare versions)

Commands

`
Usage:
n8n-debug init Initialize directory with guidelines and .env template
n8n-debug list List all workflows
n8n-debug search Search workflows by name
n8n-debug errors [limit] Show recent errors for a workflow
n8n-debug health Check workflow health and execution stats
n8n-debug validate Validate workflow JSON before pushing
n8n-debug activate [ ...] Activate one or more workflows
n8n-debug deactivate [ ...] Deactivate one or more workflows
n8n-debug diff Compare two workflows and show differences
n8n-debug compare-executions Compare successful vs failed executions
n8n-debug retry [--load-workflow] Retry a failed execution
n8n-debug pull [workflow-id|all] Pull workflow(s) to local JSON files
n8n-debug pull-executions [limit] Pull execution data for a workflow
n8n-debug push Push local workflow changes to n8n
n8n-debug clean [all|workflows|executions] Remove downloaded files
n8n-debug help Show help

Flags:
--json Output in JSON format (for agent use)

Examples:
n8n-debug search "Todoist"
n8n-debug errors mp3KdoJFgCDT5ktt --json
n8n-debug validate workflows/mp3KdoJFgCDT5ktt_Workflow.json
n8n-debug activate mp3KdoJFgCDT5ktt
n8n-debug deactivate mp3KdoJFgCDT5ktt abc123def
n8n-debug compare-executions mp3KdoJFgCDT5ktt 437776 440301
n8n-debug retry 440301 # Retry with original workflow
n8n-debug retry 440301 --load-workflow # Retry with latest workflow version
`

Workflow Development

`bash
n8n-debug search "My Workflow" # Find the workflow
n8n-debug errors # See what's failing
n8n-debug pull # Get the workflow


... edit the JSON ...


n8n-debug validate # Check it's valid
n8n-debug push # Deploy the fix
`

Note: Only core workflow fields can be updated via push:

- name - Workflow name
- nodes - Workflow nodes and their configuration
- connections - Node connections
- settings - Workflow settings
- staticData - Static workflow data

Read-only fields (like active, tags, timestamps) are filtered out and must be changed in the n8n UI.

Security Notes

workflows/ and especially executions/` can include production data, credentials and PII from n8n runs. Treat those folders as sensitive artifacts and avoid syncing or uploading them to shared repos or cloud storage unless they are scrubbed.