---
name: apify-debug-bundle
description: |-
  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".
allowed-tools: Read, Bash(curl:*), Bash(npm:*), Bash(node:*), Bash(tar:*), Bash(apify:*), Grep
version: 1.5.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
  - saas
  - scraping
  - automation
  - apify
compatibility: Designed for Claude Code
title: apify-debug-bundle
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle
last_updated: 2026-10-07T06:06:28.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle/references/examples.md), [references/implementation.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle/references/implementation.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/apify-debug-bundle`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/apify-debug-bundle`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/apify-debug-bundle --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/apify-debug-bundle --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle/references/implementation.md).

1. **Investigate the failed run** — pull run summary, dataset stats, and the log
   tail via the SDK. The core call:

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

2. **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](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle/references/implementation.md).

3. **Compare against a good run** (optional) — diff a successful and failed run
   field-by-field to spot the delta (`compareRuns(successId, failId)`).

4. **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](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle/references/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

1. Check run log for stack trace
2. Compare with a successful run
3. Check [Apify Status](https://status.apify.com) for outages
4. Create debug bundle
5. Submit to [Apify Support](https://console.apify.com/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](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle/references/examples.md). The quickest path:

```bash
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](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle/references/examples.md) for the full walkthroughs, including
reading the comparison output and interpreting a live tail.

## Resources

- [Full implementation walkthrough](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle/references/implementation.md)
- [Worked examples](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/apify-debug-bundle/references/examples.md)
- [Actor Run API](https://docs.apify.com/api/v2/actor-run-get)
- [Run Log API](https://docs.apify.com/api/v2)
- [Apify Support Portal](https://console.apify.com/support)

## Next Steps

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