Agent skill
exa-debug-bundle
Collect Exa debug evidence for support tickets and troubleshooting. Use when encountering persistent issues, preparing support tickets, or collecting diagnostic information for Exa problems. Trigger with phrases like "exa debug", "exa support bundle", "collect exa logs", "exa diagnostic".
Install this agent skill to your Project
npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/exa-pack/skills/exa-debug-bundle
SKILL.md
Exa Debug Bundle
Current State
!node --version 2>/dev/null || echo 'N/A'
!npm list exa-js 2>/dev/null | grep exa-js || echo 'exa-js not installed'
!echo "EXA_API_KEY: ${EXA_API_KEY:+SET (${#EXA_API_KEY} chars)}"
Overview
Collect all necessary diagnostic information for Exa support tickets. Exa error responses include a requestId field — always include it when contacting support at hello@exa.ai.
Instructions
Step 1: Quick Connectivity Test
set -euo pipefail
echo "=== Exa Connectivity Test ==="
echo "API Key: ${EXA_API_KEY:+SET (${#EXA_API_KEY} chars)}"
echo ""
# Test basic search endpoint
HTTP_CODE=$(curl -s -o /tmp/exa-debug.json -w "%{http_code}" \
-X POST https://api.exa.ai/search \
-H "x-api-key: $EXA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"debug connectivity test","numResults":1}')
echo "HTTP Status: $HTTP_CODE"
if [ "$HTTP_CODE" = "200" ]; then
echo "Status: HEALTHY"
python3 -c "import json; d=json.load(open('/tmp/exa-debug.json')); print(f'Results: {len(d.get(\"results\",[]))}')" 2>/dev/null
else
echo "Status: UNHEALTHY"
echo "Response:"
cat /tmp/exa-debug.json | python3 -m json.tool 2>/dev/null || cat /tmp/exa-debug.json
fi
Step 2: Capture Request/Response Details
import Exa from "exa-js";
const exa = new Exa(process.env.EXA_API_KEY);
async function debugSearch(query: string) {
const startTime = performance.now();
try {
const result = await exa.searchAndContents(query, {
numResults: 3,
text: { maxCharacters: 500 },
});
const duration = performance.now() - startTime;
console.log("=== Debug Info ===");
console.log(`Query: "${query}"`);
console.log(`Duration: ${duration.toFixed(0)}ms`);
console.log(`Results: ${result.results.length}`);
console.log(`Has autoprompt: ${!!result.autopromptString}`);
for (const r of result.results) {
console.log(` [${r.score.toFixed(3)}] ${r.title} (${r.url})`);
console.log(` Text: ${r.text ? `${r.text.length} chars` : "none"}`);
}
} catch (err: any) {
const duration = performance.now() - startTime;
console.error("=== Error Debug ===");
console.error(`Query: "${query}"`);
console.error(`Duration: ${duration.toFixed(0)}ms`);
console.error(`Status: ${err.status || "unknown"}`);
console.error(`Message: ${err.message}`);
console.error(`RequestId: ${err.requestId || err.request_id || "none"}`);
console.error(`Error tag: ${err.error_tag || err.tag || "none"}`);
}
}
Step 3: Create Debug Bundle Script
#!/bin/bash
set -euo pipefail
# exa-debug-bundle.sh
BUNDLE_DIR="exa-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"
echo "=== Exa Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
# Environment info
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'N/A')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -a)" >> "$BUNDLE_DIR/summary.txt"
echo "EXA_API_KEY: ${EXA_API_KEY:+SET}" >> "$BUNDLE_DIR/summary.txt"
# SDK version
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- SDK ---" >> "$BUNDLE_DIR/summary.txt"
npm list exa-js 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "exa-js not found" >> "$BUNDLE_DIR/summary.txt"
# API connectivity test
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- API Test ---" >> "$BUNDLE_DIR/summary.txt"
HTTP_CODE=$(curl -s -o "$BUNDLE_DIR/api-response.json" -w "%{http_code}" \
-X POST https://api.exa.ai/search \
-H "x-api-key: ${EXA_API_KEY:-missing}" \
-H "Content-Type: application/json" \
-d '{"query":"debug test","numResults":1}' 2>/dev/null)
echo "HTTP Status: $HTTP_CODE" >> "$BUNDLE_DIR/summary.txt"
# Package bundle
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo ""
echo "IMPORTANT: Review $BUNDLE_DIR/summary.txt before sharing."
echo "Include the requestId from any error responses when contacting hello@exa.ai"
Output
exa-debug-YYYYMMDD-HHMMSS.tar.gzarchive containing:summary.txt— environment, SDK version, API connectivityapi-response.json— raw API response from test query
Sensitive Data Handling
Always redact before sharing:
- API keys and tokens
- Query content containing PII
- Internal URLs or domain names
Safe to include:
- HTTP status codes and error tags
requestIdfrom error responses- SDK and runtime versions
- Latency measurements
Error Handling
| Issue | Cause | Solution |
|---|---|---|
curl: command not found |
curl not installed | Install curl or use node script |
| Empty API response | Network firewall | Check outbound HTTPS to api.exa.ai |
| 401 in connectivity test | Bad API key | Regenerate at dashboard.exa.ai |
| Bundle script fails | Missing permissions | Run with bash not sh |
Resources
- Exa Error Codes
- Exa Support
Next Steps
For rate limit issues, see exa-rate-limits. For common error solutions, see exa-common-errors.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
dockerfile-generator
Dockerfile Generator - Auto-activating skill for DevOps Basics. Triggers on: dockerfile generator, dockerfile generator Part of the DevOps Basics skill category.
branch-naming-helper
Branch Naming Helper - Auto-activating skill for DevOps Basics. Triggers on: branch naming helper, branch naming helper Part of the DevOps Basics skill category.
readme-generator
Readme Generator - Auto-activating skill for DevOps Basics. Triggers on: readme generator, readme generator Part of the DevOps Basics skill category.
makefile-generator
Makefile Generator - Auto-activating skill for DevOps Basics. Triggers on: makefile generator, makefile generator Part of the DevOps Basics skill category.
gitignore-generator
Gitignore Generator - Auto-activating skill for DevOps Basics. Triggers on: gitignore generator, gitignore generator Part of the DevOps Basics skill category.
pre-commit-hook-setup
Pre Commit Hook Setup - Auto-activating skill for DevOps Basics. Triggers on: pre commit hook setup, pre commit hook setup Part of the DevOps Basics skill category.
Didn't find tool you were looking for?