skills.rest
activepieces
activepiecesOFFICIAL
Explore all skills by this author →
WebsiteGitHub

debug-failed-run

Diagnose failed Activepieces flow runs by correlating BullMQ jobs, Postgres rows, and ClickHouse logs.

24.2k|4.1k|Updated Dec 3, 2022
Search Tags:#ssh#BullMQ#Debugging#Root Cause Analysis#clickhouse#activepieces#flow run
One-click install
npx skills add https://github.com/activepieces/activepieces --skill debug-failed-run
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: debug-failed-run
Source: https://github.com/activepieces/activepieces/tree/main/.agents/skills/debug-failed-run
Command: npx skills add https://github.com/activepieces/activepieces --skill debug-failed-run

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When an Activepieces flow run fails, the root cause is scattered across BullMQ job state, Postgres rows, compressed run logs, and centralized ClickHouse logs. This Skill walks you through an end-to-end investigation that joins all of these sources and classifies the failure as a product bug, user/config issue, or infrastructure problem.

Core Features & Use Cases

  • Remote job/run report: Runs a debug script over SSH on the DevOps box to pull the BullMQ job, flow_run, flow_version, flow, trigger payload, and run logs as a single JSON report.
  • ClickHouse log correlation: Queries centralized server/worker logs via the ClickStack MCP around the failure window to find sandbox crashes, OOM events, RPC timeouts, and connection refresh failures.
  • Code-level root cause tracing: Greps the Activepieces repo for the exact error message or ActivepiecesError code to locate the throwing file:line and decide whether it is a product bug or a config issue.
  • Backlog categorization: Aggregates all failed jobs in the workerJobs queue into categories (ConnectionNotFound, StorageError, stalled, SANDBOX_INTERNAL_ERROR, etc.) with counts and sample job ids.
  • Use Case: Given a failed run id, produce a one-line root cause, the failing step and quoted stacktrace, corroborating log lines, and either a proposed code fix or the config change the user must make.

Quick Start

Ask the assistant to debug failed flow run <run-id> using the debug-failed-run skill, providing the SSH host for the DevOps box.

Frequently Asked Questions about debug-failed-run

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a failed Activepieces flow run?▼

Provide the flow run id and the SSH host of your DevOps box. The skill runs a remote script that joins the BullMQ job, Postgres flow_run/flow_version rows, and run logs into one JSON report, then correlates the failure with ClickHouse logs and the source code.

How do I find the root cause of an Internal error in Activepieces?▼

The BullMQ failedReason 'Internal error' is a generic wrapper; the real cause is in the job stacktrace and ClickHouse logs. The skill extracts the distinctive error message or ActivepiecesError code and greps the repo to locate the throwing code path.

Can I categorize all failed jobs in the Activepieces queue at once?▼

Yes. Running the aggregate-internal-errors script over SSH scans all failed jobs in the workerJobs queue and classifies them into categories like ConnectionNotFound, StorageError, stalled jobs, RPC timeouts, and SANDBOX_INTERNAL_ERROR with counts and sample job ids.

Why can't the debug script decompress Activepieces run logs?▼

Run-log bodies are ZSTD-compressed and require Node 22.15 or later, while the DevOps box runs Node v20. The job and database data is still complete; the skill retrieves the actual log lines from ClickHouse instead.

What access do I need to debug Activepieces flow failures?▼

You need SSH access to the DevOps box hosting the debug scripts in /root/queue, the ClickStack MCP configured for ClickHouse log queries, and a local checkout of the Activepieces repository for code tracing.

Related Skills

Explore More Software Engineering Skills→
mattwoodcomattwoodco
3

docker

Set up a Docker Compose local development environment with multiple services.

Community
Advanced
meta-pytorchmeta-pytorch
2.5k

implement

Generate minimal code changes to fix failing tests from /write-tests runs.

Official
Intermediate
VKirillVKirill
15

bullmq

Builds BullMQ 5.x background jobs with Redis-backed queues, workers, and FlowProducer pipelines.

Community
Advanced
komlukkomluk
15

mcp-tools

Select MCP plugins over built-in tools with fallback behavior.

Community
Intermediate