ClickUp Debug Bundle
Overview
Collect diagnostic information for troubleshooting ClickUp API v2 issues. Generates a redacted bundle safe for sharing with support.
Quick Health Check
#!/bin/bash
echo "=== ClickUp Quick Health Check ==="
echo -n "Auth: "
AUTH_RESULT=$(curl -s -w "\n%{http_code}" \
https://api.clickup.com/api/v2/user \
-H "Authorization: $CLICKUP_API_TOKEN")
HTTP_CODE=$(echo "$AUTH_RESULT" | tail -1)
[ "$HTTP_CODE" = "200" ] && echo "OK (200)" || echo "FAILED ($HTTP_CODE)"
echo -n "Rate limits: "
HEADERS=$(curl -s -D - -o /dev/null \
https://api.clickup.com/api/v2/user \
-H "Authorization: $CLICKUP_API_TOKEN" 2>&1)
REMAINING=$(echo "$HEADERS" | grep -i "X-RateLimit-Remaining" | awk '{print $2}' | tr -d '\r')
LIMIT=$(echo "$HEADERS" | grep -i "X-RateLimit-Limit" | awk '{print $2}' | tr -d '\r')
echo "${REMAINING}/${LIMIT} remaining"
echo "Workspaces:"
curl -s https://api.clickup.com/api/v2/team \
-H "Authorization: $CLICKUP_API_TOKEN" | \
python3 -c "import sys,json; [print(f' {t[\"id\"]}: {t[\"name\"]}') for t in json.load(sys.stdin).get('teams',[])]" 2>/dev/null
echo -n "ClickUp status: "
curl -s https://status.clickup.com/api/v2/summary.json 2>/dev/null | \
python3 -c "import sys,json; print(json.load(sys.stdin)['status']['description'])" 2>/dev/null || echo "Unable to check"
echo -n "API latency: "
LATENCY=$(curl -s -o /dev/null -w "%{time_total}" \
https://api.clickup.com/api/v2/user \
-H "Authorization: $CLICKUP_API_TOKEN")
echo "${LATENCY}s"
Full Debug Bundle Script
#!/bin/bash
BUNDLE_DIR="clickup-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"
cat > "$BUNDLE_DIR/summary.txt" <<HEADER
ClickUp Debug Bundle
Generated: $(date -Iseconds)
Hostname: $(hostname)
Node: $(node --version 2>/dev/null || echo 'N/A')
CLICKUP_API_TOKEN: ${CLICKUP_API_TOKEN:+[SET (${#CLICKUP_API_TOKEN} chars)]}
HEADER
echo -e "\n--- Auth Check ---" >> "$BUNDLE_DIR/summary.txt"
curl -s -D "$BUNDLE_DIR/auth-headers.txt" -o "$BUNDLE_DIR/auth-response.json" \
https://api.clickup.com/api/v2/user \
-H "Authorization: $CLICKUP_API_TOKEN"
echo "HTTP status: $(head -1 "$BUNDLE_DIR/auth-headers.txt")" >> "$BUNDLE_DIR/summary.txt"
echo -e "\n--- Rate Limit Headers ---" >> "$BUNDLE_DIR/summary.txt"
grep -i "ratelimit" "$BUNDLE_DIR/auth-headers.txt" >> "$BUNDLE_DIR/summary.txt" 2>/dev/null
echo -e "\n--- Workspaces ---" >> "$BUNDLE_DIR/summary.txt"
curl -s https://api.clickup.com/api/v2/team \
-H "Authorization: " >
f /*.json;
[ -f ] && sed -i
-f
tar -czf
-rf
Programmatic Diagnostics
interface ClickUpDiagnostics {
auth: { ok: boolean; userId?: number; username?: string };
rateLimit: { limit: number; remaining: number; resetAt: string };
workspaces: Array<{ id: string; name: string; memberCount: number }>;
latencyMs: number;
platformStatus: string;
}
async function collectDiagnostics(): Promise<ClickUpDiagnostics> {
const start = Date.now();
const response = await fetch('https://api.clickup.com/api/v2/user', {
headers: { 'Authorization': process.env.CLICKUP_API_TOKEN! },
});
const latencyMs = Date.now() - start;
const rateLimit = {
limit: parseInt(response.headers.get() ?? ),
: (response..() ?? ),
: (
(response..() ?? ) *
).(),
};
: [];
(response.) {
data = response.();
auth = { : , : data.., : data.. };
} {
auth = { : };
}
teamsRes = (, {
: { : process..! },
});
teams = teamsRes. ? teamsRes.() : { : [] };
{
auth,
rateLimit,
: teams..( ({
: t., : t., : t.?. ?? ,
})),
latencyMs,
: auth. ? : ,
};
}
Error Handling
| Issue | Diagnostic Check | Solution |
|---|
| Auth failing | Check HTTP status on /user | Regenerate token |
| High latency (>2s) | Check latencyMs | Network/region issue |
| Rate limited (0 remaining) | Check X-RateLimit-Remaining | Wait for reset or upgrade plan |
| Workspace missing | Check teams.json | Re-authorize workspace |
Resources
Next Steps
For rate limit issues, see clickup-rate-limits.
