# n8n Failed Execution Doctor (`boris-automation/my-actor`) Actor

Diagnose failed n8n executions from exported workflow and execution JSON. Find the failing node, classify the root cause, redact common secret-like strings, and get the next diagnostic step. No live n8n access or external LLM. Unofficial; not affiliated with n8n GmbH.

- **URL**: https://apify.com/boris-automation/my-actor.md
- **Developed by:** [Boris](https://apify.com/boris-automation) (community)
- **Categories:** Integrations, Developer tools, Automation
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## n8n Failed Execution Doctor

> **Unofficial community tool.** This project is not affiliated with, endorsed by, or sponsored by n8n GmbH.

[![CI](https://github.com/corleoneappsh-create/n8n-failed-execution-doctor-public/actions/workflows/test.yaml/badge.svg)](https://github.com/corleoneappsh-create/n8n-failed-execution-doctor-public/actions/workflows/test.yaml)
[![Release](https://img.shields.io/github/v/release/corleoneappsh-create/n8n-failed-execution-doctor-public)](https://github.com/corleoneappsh-create/n8n-failed-execution-doctor-public/releases)

Diagnose a failed n8n execution without connecting to the customer's live n8n instance.

[![n8n Failed Execution Doctor Pro preview](https://n8n-doctor.167-233-67-162.sslip.io/n8n-doctor-pro-hero.png)](https://n8n-doctor.167-233-67-162.sslip.io/?src=github)

Provide two JSON objects:

- the exported n8n workflow;
- the failed execution JSON.

The Actor returns the failing node, node type, normalized error category, sanitized error message, and a concrete next diagnostic step.

### Why this is different

This is not another generic workflow linter. It focuses on incidents that already happened: failed runs, timeouts, authentication failures, rate limits, invalid API payloads, expression/item-linking errors, and network failures.

It is deterministic: no external LLM call is required for the core diagnosis, which keeps latency and platform cost low.

### Free Lite n8n workflow

Want to run the same core diagnosis entirely inside n8n? **[Download the Lite workflow JSON](https://github.com/corleoneappsh-create/n8n-failed-execution-doctor-public/releases/latest/download/n8n-failed-execution-doctor-lite.json)** or inspect [`examples/n8n-failed-execution-doctor-lite.json`](examples/n8n-failed-execution-doctor-lite.json).

The Lite workflow uses only two core n8n nodes (`Execute Workflow Trigger` + `Code`), requires no external API key or LLM, and returns the failing node, root-cause category, sanitized error message, and a focused next diagnostic step for one incident item.

The exact JSON in this repository has been imported successfully into an isolated **n8n 2.33.7** runtime. It is inactive by default.

### Pro workflow — batch diagnosis and incident reports

If you need a self-contained n8n workflow rather than the Actor, **n8n Failed Execution Doctor Pro v0.3.0** adds:

- batch diagnosis for multiple failed-execution items in one run;
- deterministic severity and retry-safety heuristics;
- workflow risk hints;
- ready-to-copy Markdown incident reports;
- sample input/output and a commercial internal-use license.

It requires no external LLM, API key, database, or live n8n login. The Pro workflow has been imported and executed end-to-end on n8n 2.33.7.

**Pro details and purchase:** https://n8n-doctor.167-233-67-162.sslip.io/?src=github

#### Reliability Toolkit bundle — $29

If you also want to catch workflow risks **before deployment**, the Reliability Toolkit Pro includes Incident Doctor Pro plus a zero-dependency preflight scanner, Markdown/JSON reports, broken-connection and webhook checks, domain/credential inventory, and a ready-to-use GitHub CI template.

**Toolkit details:** https://n8n-doctor.167-233-67-162.sslip.io/?src=github

#### Lite vs Pro

| Capability | Free Lite | Pro v0.3.0 |
|---|:---:|:---:|
| Failing/last node detection | ✓ | ✓ |
| Root-cause classification | ✓ | ✓ |
| Sanitized error evidence | ✓ | ✓ |
| Focused next diagnostic step | ✓ | ✓ |
| Batch incident diagnosis | — | ✓ |
| Severity heuristic | — | ✓ |
| Retry-safety guidance | — | ✓ |
| Workflow risk hints | — | ✓ |
| Markdown incident report | — | ✓ |
| Sample input/output package | — | ✓ |

### Privacy boundary

The Actor does not need n8n credentials and does not log in to a live n8n instance. Common secret-like strings in error messages are redacted and returned messages are truncated. Users should still remove unnecessary sensitive execution data before submitting JSON.

### Categories detected

- `authentication`: 401/403, authorization, credential and token failures;
- `rate_limit`: HTTP 429 and rate-limit responses;
- `timeout`: timeout, ETIMEDOUT and ECONNABORTED;
- `network`: connection, DNS, socket and reachability failures;
- `invalid_input`: HTTP 400/422, validation and malformed request failures;
- `expression`: undefined fields, expression and item-linking problems;
- `execution_error`: structured failures that do not match a more specific class.

### Output

Each run writes one diagnosis to the default dataset and to the `DIAGNOSIS` key-value record. A no-error input returns `NO_STRUCTURED_ERROR_FOUND` rather than inventing a root cause.

### Apify deployment

The code supports Apify pay-per-event through the `incident-diagnosed` event. Configure that event in Apify Console and set `ACTOR_CHARGE_EVENT_NAME=incident-diagnosed` for the production Actor.

Local PPE validation has been completed with Apify's test mode and a single charge event per completed diagnosis.

# Actor input Schema

## `workflow` (type: `object`):

Exported n8n workflow object. A safe synthetic demo is prefilled so the Actor can be tested immediately.

## `execution` (type: `object`):

Saved or API-returned failed n8n execution object. A synthetic 401 failure is prefilled; remove sensitive data from real exports.

## Actor input object example

```json
{
  "workflow": {
    "name": "Demo Lead Sync",
    "nodes": [
      {
        "name": "CRM API",
        "type": "n8n-nodes-base.httpRequest"
      }
    ]
  },
  "execution": {
    "data": {
      "resultData": {
        "lastNodeExecuted": "CRM API",
        "runData": {
          "CRM API": [
            {
              "error": {
                "message": "Request failed: unauthorized",
                "httpCode": 401
              }
            }
          ]
        }
      }
    }
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `diagnosis` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "workflow": {
        "name": "Demo Lead Sync",
        "nodes": [
            {
                "name": "CRM API",
                "type": "n8n-nodes-base.httpRequest"
            }
        ]
    },
    "execution": {
        "data": {
            "resultData": {
                "lastNodeExecuted": "CRM API",
                "runData": {
                    "CRM API": [
                        {
                            "error": {
                                "message": "Request failed: unauthorized",
                                "httpCode": 401
                            }
                        }
                    ]
                }
            }
        }
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("boris-automation/my-actor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "workflow": {
        "name": "Demo Lead Sync",
        "nodes": [{
                "name": "CRM API",
                "type": "n8n-nodes-base.httpRequest",
            }],
    },
    "execution": { "data": { "resultData": {
                "lastNodeExecuted": "CRM API",
                "runData": { "CRM API": [{ "error": {
                                "message": "Request failed: unauthorized",
                                "httpCode": 401,
                            } }] },
            } } },
}

# Run the Actor and wait for it to finish
run = client.actor("boris-automation/my-actor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "workflow": {
    "name": "Demo Lead Sync",
    "nodes": [
      {
        "name": "CRM API",
        "type": "n8n-nodes-base.httpRequest"
      }
    ]
  },
  "execution": {
    "data": {
      "resultData": {
        "lastNodeExecuted": "CRM API",
        "runData": {
          "CRM API": [
            {
              "error": {
                "message": "Request failed: unauthorized",
                "httpCode": 401
              }
            }
          ]
        }
      }
    }
  }
}' |
apify call boris-automation/my-actor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,boris-automation/my-actor"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/9NQ7qXPzps7fxvUa6/builds/TaYrA6COH6Pr1gKKz/openapi.json