n8n Execution Error Intelligence Dashboard

A local dashboard that connects to your n8n instance, surfaces failed workflow executions, classifies errors, identifies repeating patterns, and gives AI-generated fix suggestions powered by Google Gemini.

Screenshots

Main dashboard — workflow selector, KPIs, and execution table

Repeating Errors section — groups the same error across executions and shows AI-generated root cause and fix

Detail panel — failed node, error message, category, and AI explanation

What it does

• Shows all failed executions across workflows in one place
• Groups repeated error messages and tells you how many times each has occurred and in which node/workflow
• Classifies errors by category (Authentication, Timeout, AI Model Error, Data Validation, API Failure)
• One-click AI fix suggestions — Gemini analyses each repeating error and returns a root cause and concrete fix
• Per-execution detail panel with AI explanation of what happened and what to do
• Retry executions directly from the dashboard

Prerequisites

• Node.js 18+
• An n8n instance (self-hosted or n8n Cloud)
• n8n API key (Settings → API in your n8n instance)
• Google Gemini API key (get one free at aistudio.google.com)

Setup

1. Clone and install

git clone <repo-url>
cd n8n_debugger
npm install

2. Create your .env file

Create a .env file in the project root:

VITE_N8N_BASE_URL=https://your-instance.app.n8n.cloud/api/v1
VITE_N8N_API_KEY=your_n8n_api_key_here
VITE_GEMINI_API_KEY=your_gemini_api_key_here

Important notes on VITE_N8N_BASE_URL:

• Must include the /api/v1 path — e.g. https://yourname.app.n8n.cloud/api/v1
• No trailing slash
• For self-hosted n8n, it would be something like http://localhost:5678/api/v1

How to get your n8n API key:

1. Open your n8n instance
2. Go to Settings → n8n API
3. Create a new API key and copy it

How to get a Gemini API key:

1. Go to aistudio.google.com
2. Click Get API key → Create API key
3. Copy it into your .env

3. Run the dev server

npm run dev

Open http://localhost:5173 in your browser.

How the proxy works

The Vite dev server proxies all API requests to your n8n instance to avoid CORS issues. Your API key is injected server-side via the proxy — it is never exposed in the browser. This means:

• The .env file and API keys are only used at dev-server time, not shipped to the browser
• You can safely run this locally without worrying about key exposure

Tech stack

Layer	Library
Framework	React 18 + TypeScript
Build tool	Vite 7
Styling	Tailwind CSS v4
AI	Google Gemini (gemini-2.5-flash) via @google/generative-ai
Date handling	date-fns
Icons	@heroicons/react

Project structure

src/
  types/          execution.ts, ai.ts, ui.ts
  services/       n8nClient.ts, executionService.ts, workflowService.ts, aiService.ts
  utils/          errorClassifier.ts, errorCleaner.ts, formatters.ts, kpiCalculator.ts
  hooks/          useExecutions.ts, useExecutionDetail.ts, useWorkflows.ts, useKpis.ts
  components/
    layout/       Sidebar.tsx, TopBar.tsx
    kpi/          KpiBar.tsx, KpiCard.tsx, RepeatingErrorsSummary.tsx
    executions/   ExecutionTable.tsx, ExecutionRow.tsx, ExecutionFilters.tsx
    detail/       DetailPanel.tsx, FailedNodeCard.tsx, AiExplainer.tsx
    actions/      RetryButton.tsx, RaiseIncidentButton.tsx

Troubleshooting

503 error on startup The dashboard fetches the execution list first (lightweight), then fetches details for failed executions one by one. If you still get 503s, check that your VITE_N8N_BASE_URL is correct and your n8n instance is reachable.

"Verify connectivity to the n8n instance" error Your VITE_N8N_BASE_URL is likely wrong. Make sure it includes /api/v1 and has no trailing slash. Restart the dev server after changing .env.

Repeating Errors section shows nothing This section only shows error messages that have occurred 2 or more times within the selected time range. If all your errors are unique or you have fewer than 2 failures, it will be empty.

AI features not working Check that VITE_GEMINI_API_KEY is set correctly in your .env and restart the dev server.