# Actor Troubleshooter (`jiri.spilka/actor-troubleshooter`) Actor Diagnoses problems with any Apify Actor and (optionally) drafts a reply for the maintainer to send to the user. Investigates via MCP: input schema, README, run logs, and dataset samples. Returns structured analysis plus a per-step debug trace. - **URL**: https://apify.com/jiri.spilka/actor-troubleshooter.md - **Developed by:** [Jiří Spilka](https://apify.com/jiri.spilka) (community) - **Categories:** AI, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ### What does Actor Troubleshooter do? **Actor Troubleshooter** diagnoses problems with any Apify Actor and (optionally) drafts a polished reply for the maintainer to send back to the user. Provide the Actor's ID plus whatever context you have — a failing run ID, the input the user used, an error message, or a thread of issue comments — and the Actor uses the [Apify MCP server](https://mcp.apify.com/) to investigate: it fetches the Actor's input schema and README, inspects the run logs and dataset, and traces the problem to its real root cause. The output is a single dataset item containing the structured analysis (summary, root cause, evidence, fix steps, verification, confidence), a pre-formatted `debugTrace` for the maintainer to review, and a `trace` array with every tool call the underlying agent made — so you can audit its reasoning end-to-end. ### Why use Actor Troubleshooter? - **Faster triage** — investigation steps that would take minutes (open the Actor, read the schema, find the run, scan logs, sample the dataset) happen in one call. - **Consistent diagnoses** — every run produces the same structured fields, so you can pipe the output into a CRM, dashboard, or webhook. - **Auditable reasoning** — every tool call and result is captured in the `trace` field on the same dataset item. - **Optional drafted reply** — when the input includes an issue thread, the Actor produces a friendly, ready-to-post comment in the user's voice. ### How to use Actor Troubleshooter 1. Get your [Apify API token](https://console.apify.com/account/integrations). 2. Call the Actor synchronously, providing whatever context you have: ```bash curl -X POST "https://api.apify.com/v2/acts/jiri.spilka~actor-troubleshooter/run-sync-get-dataset-items?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "actorId": "apify/rag-web-browser", "runId": "abcdef0123", "errorMessage": "Run failed with timeout after 40s.", "task": "diagnose-and-draft-reply" }' ``` 3. Read the first dataset item — it contains the structured analysis, the pre-formatted `debugTrace`, and the per-step `trace`. ### Input `actorId` is required. Everything else is optional — provide what you have. | Field | Type | Description | | --------------- | ------ | ------------------------------------------------------------------------------ | | `actorId` | string | Apify Actor ID or `username/actor-name` slug (e.g. `apify/instagram-scraper`). | | `runId` | string | Failing run ID. The agent inspects status, logs, input, and dataset. | | `userInput` | object | The input the user passed to the Actor (validated against the Actor's schema). | | `errorMessage` | string | Error message reported by the user or the run. | | `issueTitle` | string | Title of the issue / ticket the user filed. | | `issueComments` | array | Thread comments, each `{ "author": "...", "content": "..." }`. | | `task` | enum | `diagnose`, `draft-reply`, or `diagnose-and-draft-reply` (default). | ### Output A single dataset item per run, containing the structured analysis and the per-step debug trace. ```jsonc { "summary": "Run timed out because broad search terms return JS-heavy pages.", "rootCause": "requestTimeoutSecs (40 s) exceeded by 3 heavy pages scraped in parallel.", "evidence": [ "Schema: maxResults default = 3", "Schema: requestTimeoutSecs default = 40", "Common queries return CNN/BBC/Wikipedia which are JS-heavy", ], "fix": { "steps": ["Reduce maxResults to 1", "Increase requestTimeoutSecs to 60"], "exampleInput": { "query": "...", "maxResults": 1, "requestTimeoutSecs": 60 }, }, "verification": "Re-run the broad query with these settings; should complete under 60 s.", "confidence": "High", "gaps": [], "userFacingReply": "Hi, thanks for reporting this — here's what's happening… ", "debugTrace": "--- DEBUG TRACE ---\nSummary: ...\nRoot cause: ...\nTools called: fetch-actor-details\nConfidence: High\n--- END DEBUG TRACE ---", "trace": [ { "text": "", "finishReason": "tool-calls", "usage": { "inputTokens": 800, "outputTokens": 40 }, "toolCalls": [{ "toolName": "fetch-actor-details", "input": { "actorId": "apify/rag-web-browser" } }], "toolResults": [{ "toolName": "fetch-actor-details", "output": "...[truncated 44288 chars]" }], }, ], "meta": { "model": "anthropic/claude-opus-4.6", "investigationFinishReason": "stop", "investigationUsage": { "inputTokens": 13560, "outputTokens": 1340 }, "formattingUsage": { "inputTokens": 1500, "outputTokens": 400 }, }, } ```` `userFacingReply` is `null` when `task` is `diagnose`; `fix.exampleInput` is `null` when no input change is required. `debugTrace` is a pre-formatted block that maintainers can prepend to the reply for review and delete before posting. `trace` carries one entry per LLM step (tool calls, tool results, usage) so reviewers can audit the agent's reasoning end-to-end. ### Pricing You are billed for two things on each call: - **Apify platform runtime** — the compute units this Actor consumes, typically a few minutes of standard runtime per call. - **OpenRouter LLM usage** — the underlying model calls (investigation + formatting), billed via [OpenRouter Actor](https://apify.com/apify/openrouter). Both runs are visible in the Apify Console, so you can audit the full cost of every call. # Actor input Schema ## `actorId` (type: `string`): Apify Actor ID or `username/actor-name` slug, e.g. `apify/instagram-scraper`. ## `runId` (type: `string`): When provided, the agent inspects the run's status, logs, input, and dataset. ## `userInput` (type: `object`): The input the user passed to the Actor (if known). Used to validate against the Actor's input schema. ## `errorMessage` (type: `string`): An error message the user reported or the run produced. ## `issueTitle` (type: `string`): Title of the issue the user filed (when troubleshooting from a support ticket). ## `issueComments` (type: `array`): Issue thread comments. Each item is an object with `author` and `content` fields. ## `task` (type: `string`): What the Actor should produce. ## Actor input object example ```json { "task": "diagnose-and-draft-reply" } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("jiri.spilka/actor-troubleshooter").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("jiri.spilka/actor-troubleshooter").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call jiri.spilka/actor-troubleshooter --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=jiri.spilka/actor-troubleshooter", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Actor Troubleshooter", "description": "Diagnoses problems with any Apify Actor and (optionally) drafts a reply for the maintainer to send to the user. Investigates via MCP: input schema, README, run logs, and dataset samples. Returns structured analysis plus a per-step debug trace.", "version": "0.2", "x-build-id": "It200ZBSU989r3puc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jiri.spilka~actor-troubleshooter/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jiri.spilka-actor-troubleshooter", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/jiri.spilka~actor-troubleshooter/runs": { "post": { "operationId": "runs-sync-jiri.spilka-actor-troubleshooter", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/jiri.spilka~actor-troubleshooter/run-sync": { "post": { "operationId": "run-sync-jiri.spilka-actor-troubleshooter", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "actorId" ], "properties": { "actorId": { "title": "Actor ID or name", "type": "string", "description": "Apify Actor ID or `username/actor-name` slug, e.g. `apify/instagram-scraper`." }, "runId": { "title": "Failing run ID", "type": "string", "description": "When provided, the agent inspects the run's status, logs, input, and dataset." }, "userInput": { "title": "User-provided input", "type": "object", "description": "The input the user passed to the Actor (if known). Used to validate against the Actor's input schema." }, "errorMessage": { "title": "Error message", "type": "string", "description": "An error message the user reported or the run produced." }, "issueTitle": { "title": "Issue title", "type": "string", "description": "Title of the issue the user filed (when troubleshooting from a support ticket)." }, "issueComments": { "title": "Issue comments", "type": "array", "description": "Issue thread comments. Each item is an object with `author` and `content` fields." }, "task": { "title": "Task", "enum": [ "diagnose", "draft-reply", "diagnose-and-draft-reply" ], "type": "string", "description": "What the Actor should produce.", "default": "diagnose-and-draft-reply" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```