Apify Debug Bundle

Overview

Collect all diagnostic information needed to troubleshoot failed Actor runs and prepare Apify support tickets. Pulls run metadata, logs, dataset samples, and environment info into a single bundle so a support engineer (or you) can diagnose the failure without live access to your account.

Prerequisites

• apify-client installed
• APIFY_TOKEN configured
• A failed or problematic run ID to investigate

Authentication

All API calls authenticate with the APIFY_TOKEN as a Bearer header

(Authorization: Bearer $APIFY_TOKEN), and the SDK reads the same token from

process.env.APIFY_TOKEN. Get the token from the Apify Console under

Settings → Integrations → Personal API tokens. Never commit it — the bundle

script redacts any local .env before packaging, and the platform auto-redacts

secrets inside run logs.

Instructions

The workflow has four steps. The skeleton below is enough to run it; each step's

full implementation lives in implementation.md.

1. Investigate the failed run — pull run summary, dataset stats, and the log

tail via the SDK. The core call:

   const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
   const run = await client.run(runId).get();
   const log = await client.run(runId).log().get();

1. Create the debug bundle — run apify-debug-bundle.sh . It

collects environment info, run details, log, a 5-item dataset sample,

key-value store keys, a redacted .env, and platform health, then packages

everything into a timestamped .tar.gz. Full script in

implementation.md.

1. Compare against a good run (optional) — diff a successful and failed run

field-by-field to spot the delta (compareRuns(successId, failId)).

1. Live-tail a running Actor (optional) — stream logs when the final log is

not yet available.

For copy-pasteable code for every step, see

implementation.md.

Output

A single timestamped tarball, apify-debug-YYYYMMDD-HHMMSS.tar.gz, containing:

Attach the tarball directly to an Apify support ticket.

Sensitive Data Handling

Always redact before sharing:

• API tokens (apifyapi*)
• Proxy passwords
• PII (emails, names, IPs)
• Custom environment variables

Safe to include:

• Run IDs, Actor IDs, dataset IDs
• Error messages and stack traces
• Run configuration (memory, timeout)
• Platform health status

Escalation Path

1. Check run log for stack trace
2. Compare with a successful run
3. Check Apify Status for outages
4. Create debug bundle
5. Submit to Apify Support with bundle attached

Error Handling

Examples

Four worked scenarios — a plain FAILED run, an "it worked yesterday"

regression diff, an empty-dataset investigation, and live-tailing a hung run —

are in examples.md. The quickest path:

export APIFY_TOKEN="apify_api_..."
./apify-debug-bundle.sh abc123DEF          # → apify-debug-20260717-142530.tar.gz
tar -xzf apify-debug-*.tar.gz && tail -40 apify-debug-*/run-log.txt

See examples.md for the full walkthroughs, including

reading the comparison output and interpreting a live tail.

Resources

• Full implementation walkthrough
• Worked examples
• Actor Run API
• Run Log API
• Apify Support Portal

Next Steps

For rate limit issues, see the apify-rate-limits skill.