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 installedAPIFY_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.
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();
Create the debug bundle — run apify-debug-bundle.sh <RUN_ID>. 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.
Compare against a good run (optional) — diff a successful and failed run
field-by-field to spot the delta (compareRuns(successId, failId)).
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:
| File |
Contents |
environment.txt |
Node/npm versions, installed Apify packages, CLI version |
run-details.json |
Run status, options, stats, usage, cost |
run-log.txt |
Full run log (secrets auto-redacted by the platform) |
dataset-sample.json |
First 5 dataset items |
kv-store-keys.json |
Key-value store key listing |
env-redacted.txt |
Local .env with all values redacted |
platform-health.json |
Apify platform health snapshot |
Attach the tarball directly to an Apify support ticket.
Sensitive Data Handling
Always redact before sharing:
- API tokens (
apify_api_*)
- 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
- Check run log for stack trace
- Compare with a successful run
- Check Apify Status for outages
- Create debug bundle
- Submit to Apify Support with bundle attached
Error Handling
| Issue |
Cause |
Solution |
Run not found |
Invalid run ID or expired |
Unnamed runs expire after 7 days |
Log unavailable |
Run still in progress |
Wait for completion or stream live |
| Empty dataset |
Actor produced no output |
Check failedRequestHandler in code |
| High CU usage |
Memory too high or slow execution |
Reduce memory, optimize code |
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
Next Steps
For rate limit issues, see the apify-rate-limits skill.
1---2name: apify-debug-bundle3description: Collect Apify debug evidence for support tickets and troubleshooting. Use when an Actor run has failed, is stuck, or produced empty output and you need to gather run metadata, logs, dataset samples, and environment info before opening a support ticket. Trigger with "apify debug", "apify support bundle", "collect apify logs", "apify diagnostic", "apify run failed why".4license: MIT5---6# Apify Debug Bundle
7
8## Overview
9
10Collect 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.
11
12## Prerequisites
13
14- `apify-client` installed
15- `APIFY_TOKEN` configured
16- A failed or problematic run ID to investigate
17
18## Authentication
19
20All API calls authenticate with the `APIFY_TOKEN` as a Bearer header
21(`Authorization: Bearer $APIFY_TOKEN`), and the SDK reads the same token from
22`process.env.APIFY_TOKEN`. Get the token from the Apify Console under
23**Settings → Integrations → Personal API tokens**. Never commit it — the bundle
24script redacts any local `.env` before packaging, and the platform auto-redacts
25secrets inside run logs.
26
27## Instructions
28
29The workflow has four steps. The skeleton below is enough to run it; each step's
30full implementation lives in [implementation.md](references/implementation.md).
31
321. **Investigate the failed run** — pull run summary, dataset stats, and the log
33 tail via the SDK. The core call:
34
35 ```typescript
36 const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
37 const run = await client.run(runId).get();
38 const log = await client.run(runId).log().get();
39 ```
40
412. **Create the debug bundle** — run `apify-debug-bundle.sh <RUN_ID>`. It
42 collects environment info, run details, log, a 5-item dataset sample,
43 key-value store keys, a redacted `.env`, and platform health, then packages
44 everything into a timestamped `.tar.gz`. Full script in
45 [implementation.md](references/implementation.md).
46
473. **Compare against a good run** (optional) — diff a successful and failed run
48 field-by-field to spot the delta (`compareRuns(successId, failId)`).
49
504. **Live-tail a running Actor** (optional) — stream logs when the final log is
51 not yet available.
52
53For copy-pasteable code for every step, see
54[implementation.md](references/implementation.md).
55
56## Output
57
58A single timestamped tarball, `apify-debug-YYYYMMDD-HHMMSS.tar.gz`, containing:
59
60| File | Contents |
61|------|----------|
62| `environment.txt` | Node/npm versions, installed Apify packages, CLI version |
63| `run-details.json` | Run status, options, stats, usage, cost |
64| `run-log.txt` | Full run log (secrets auto-redacted by the platform) |
65| `dataset-sample.json` | First 5 dataset items |
66| `kv-store-keys.json` | Key-value store key listing |
67| `env-redacted.txt` | Local `.env` with all values redacted |
68| `platform-health.json` | Apify platform health snapshot |
69
70Attach the tarball directly to an Apify support ticket.
71
72## Sensitive Data Handling
73
74**Always redact before sharing:**
75
76- API tokens (`apify_api_*`)
77- Proxy passwords
78- PII (emails, names, IPs)
79- Custom environment variables
80
81**Safe to include:**
82
83- Run IDs, Actor IDs, dataset IDs
84- Error messages and stack traces
85- Run configuration (memory, timeout)
86- Platform health status
87
88## Escalation Path
89
901. Check run log for stack trace
912. Compare with a successful run
923. Check [Apify Status](https://status.apify.com) for outages
934. Create debug bundle
945. Submit to [Apify Support](https://console.apify.com/support) with bundle attached
95
96## Error Handling
97
98| Issue | Cause | Solution |
99|-------|-------|----------|
100| `Run not found` | Invalid run ID or expired | Unnamed runs expire after 7 days |
101| `Log unavailable` | Run still in progress | Wait for completion or stream live |
102| Empty dataset | Actor produced no output | Check `failedRequestHandler` in code |
103| High CU usage | Memory too high or slow execution | Reduce memory, optimize code |
104
105## Examples
106
107Four worked scenarios — a plain `FAILED` run, an "it worked yesterday"
108regression diff, an empty-dataset investigation, and live-tailing a hung run —
109are in [examples.md](references/examples.md). The quickest path:
110
111```bash
112export APIFY_TOKEN="apify_api_..."
113./apify-debug-bundle.sh abc123DEF # → apify-debug-20260717-142530.tar.gz
114tar -xzf apify-debug-*.tar.gz && tail -40 apify-debug-*/run-log.txt
115```
116
117See [examples.md](references/examples.md) for the full walkthroughs, including
118reading the comparison output and interpreting a live tail.
119
120## Resources
121
122- [Full implementation walkthrough](references/implementation.md)
123- [Worked examples](references/examples.md)
124- [Actor Run API](https://docs.apify.com/api/v2/actor-run-get)
125- [Run Log API](https://docs.apify.com/api/v2)
126- [Apify Support Portal](https://console.apify.com/support)
127
128## Next Steps
129
130For rate limit issues, see the `apify-rate-limits` skill.
gabrielmoreira