Groq Debug Bundle
Current State
!node --version 2>/dev/null || echo 'N/A'
!python3 --version 2>/dev/null || echo 'N/A'
!npm list groq-sdk 2>/dev/null | grep groq-sdk || echo 'groq-sdk not installed'
Overview
Collect all diagnostic information needed to resolve Groq API issues. Produces a redacted support bundle (a .tar.gz) with environment info, SDK version, connectivity test results, rate limit headers, per-model latency, and redacted application logs — everything a Groq support engineer needs, with secrets masked before the archive is written.
Prerequisites
GROQ_API_KEY set in environmentcurl and jq available- Access to application logs (optional — the log step is skipped if
logs/ is absent)
Instructions
The bundle is assembled by a six-step shell script. Each step appends to a file inside a timestamped $BUNDLE_DIR; the final step tars it and deletes the working copy. Run the steps in order in one shell, or paste the whole sequence into a script.
- Environment — capture OS, Node/Python versions, installed Groq SDK versions, and a masked key fingerprint (length + 4-char prefix only, never the key).
- Connectivity — hit
GET /openai/v1/models to confirm auth and count available models.
- Rate limits — send a 1-token completion and grab the
x-ratelimit-*, retry-after, and x-request-id response headers.
- Latency — time a minimal completion against each model of interest.
- Log extraction — grep recent Groq/429/rate-limit errors from
logs/*.log and mask any gsk_ keys and .env values.
- Package —
tar -czf the directory, remove the working copy, and print a review reminder.
The skeleton of Step 1 (the rest is in the full walkthrough):
#!/bin/bash
set -euo pipefail
BUNDLE_DIR="groq-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"
See references/implementation.md for the complete, copy-pasteable six-step script.
Output
A single archive named groq-debug-TIMESTAMP.tar.gz (where TIMESTAMP is YYYYMMDD-HHMMSS) containing:
| File | Purpose | Sensitive? |
|---|
environment.txt | Node/Python versions, SDK version, key fingerprint | Key prefix only |
connectivity.txt | API reachability, model count | No |
rate-limits.txt | Current rate limit headers | No |
latency.txt | Response times per model | No |
app-logs.txt | Recent error logs (redacted) | Redacted |
config-redacted.txt | Config keys only (values masked) | Redacted |
The TypeScript diagnostic (see Examples) instead prints a JSON report with auth, modelsAvailable, completion, latencyMs, model, and usage.
Error Handling
GROQ_API_KEY unset — environment.txt records NOT SET and every curl step returns 401; export the key before collecting.401 Invalid API Key — the key is wrong or revoked; the bundle still captures the failure, which is the evidence support needs.jq: command not found — install jq, or the connectivity/model-count lines will be empty (the rest of the bundle still builds).- No
logs/ directory — Step 5 is skipped silently; the bundle omits app-logs.txt rather than failing.
429 during latency/rate-limit steps — expected when debugging throttling; the captured retry-after and x-ratelimit-* headers are the point. For deeper 429 handling see groq-rate-limits.
ALWAYS Redact Before Sharing
- API keys (anything starting with
gsk_)
- Bearer tokens
- PII (emails, names, IDs)
- Internal hostnames and IPs
Examples
A quick SDK-based diagnostic that confirms auth, lists models, times a completion, and prints a JSON report:
import Groq from "groq-sdk";
const groq = new Groq();
const models = await groq.models.list();
console.log(models.data.map((m) => m.id));
Full TypeScript diagnostic, healthy/bad-key sample outputs, and an end-to-end shell run with the resulting tarball listing are in references/examples.md.
Resources
Next Steps
For rate limit and 429 throttling issues, escalate to the groq-rate-limits skill, which covers backoff strategy and quota inspection in depth.
