ElevenLabs Debug Bundle

Overview

Collect all diagnostic information needed for ElevenLabs support tickets. Gathers SDK version, API connectivity (HTTP status, DNS, TLS), quota status, voice inventory, and model availability into a single archive while redacting all secrets before anything touches disk.

Two collection paths are available and produce equivalent evidence: a shell script (no code dependency — good for servers and CI) and a programmatic TypeScript collector (good when the app already imports the SDK). The full, ready-to-run source for both lives in references/implementation.md; this file is the high-level workflow.

Prerequisites

• ElevenLabs SDK installed
• API key configured (to test connectivity)
• Access to application logs
• jq available (used by the shell script to format API responses)

Instructions

The workflow is three steps: run a collector, review the output for stray secrets, then attach it to a support ticket. Follow the summary here and open references/implementation.md for the complete scripts.

Step 1: Run a collector

Shell path — the script writes each section to summary.txt, redacts secrets, then tars and removes the working directory. The skeleton:

#!/bin/bash
# elevenlabs-debug-bundle.sh
set -euo pipefail
BUNDLE_DIR="elevenlabs-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"
# ... collect environment, SDK versions, connectivity, quota, voices, models ...
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR" && rm -rf "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"

Programmatic path — build a structured DebugReport when the SDK is already a dependency. Each section is wrapped independently so one failure still returns a partial report:

const report = await collectDebugReport();
console.log(JSON.stringify(report, null, 2));

Full source for both, including the connectivity/TLS probes and quota/voice/model collectors: references/implementation.md.

Step 2: Review for secrets

Inspect the archive before sharing — API keys, webhook secrets, and any .env value are redacted automatically, but confirm nothing sensitive slipped into an error log or stack trace.

Step 3: Submit to support

Open a ticket at https://help.elevenlabs.io, attach the bundle, and describe what you expected, what happened, steps to reproduce, and any request IDs from error responses.

Output

• elevenlabs-debug-YYYYMMDD-HHMMSS.tar.gz archive containing:
  • summary.txt — Environment, SDK, connectivity, quota, voices, models
  • config-redacted.txt — Configuration with secrets masked
  • errors.txt — Recent error logs with API keys redacted

Sensitive Data Handling

Always redacted automatically:

• API keys (replaced with ***REDACTED***)
• Webhook secrets
• Any value after = in .env files

Safe to include:

• Error messages and stack traces
• SDK/runtime versions
• Voice IDs and model IDs
• HTTP status codes and latency

Error Handling

Issue	Cause	Solution
jq: command not found	jq not installed	apt install jq or brew install jq
HTTP 0 / curl fails	Network issue	Check DNS and firewall
HTTP 401	Bad API key	Regenerate key at elevenlabs.io
Empty voice list	No voices on account	Normal for new free accounts

Examples

A healthy shell run produces a masked summary.txt whose top signals are HTTP 200, TLS valid: yes, and character_count under character_limit:

$ bash elevenlabs-debug-bundle.sh
Bundle created: elevenlabs-debug-20260717-143022.tar.gz
Review for sensitive data before sharing with support.

The programmatic collector returns the same evidence as JSON — an empty errors array with connectivity.status: 200 is healthy, while "errors": ["Voices: 429 Too Many Requests"] alongside connectivity.status: 200 isolates a rate-limit on one endpoint:

{ "connectivity": { "status": 200, "latencyMs": 214 },
  "voices": { "total": 12, "cloned": 3, "premade": 9 }, "errors": [] }

Worked runs for a healthy account, a 401 bad key, and the full JSON report: references/examples.md.

Resources

• Full implementation (shell + TypeScript)
• Worked examples and sample output
• ElevenLabs Support
• ElevenLabs Status

Next Steps

For rate limit issues, see elevenlabs-rate-limits. For common errors, see elevenlabs-common-errors.