Agent skill

hubspot-debug-bundle

Collect HubSpot debug evidence for support tickets and troubleshooting. Use when encountering persistent issues, preparing support tickets, or collecting diagnostic information for HubSpot API problems. Trigger with phrases like "hubspot debug", "hubspot support bundle", "collect hubspot logs", "hubspot diagnostic", "hubspot correlation id".

Stars 1,803
Forks 241

Install this agent skill to your Project

npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/hubspot-pack/skills/hubspot-debug-bundle

SKILL.md

HubSpot Debug Bundle

Overview

Collect all necessary diagnostic information for HubSpot API troubleshooting and support ticket escalation, including correlation IDs, rate limit state, and SDK versions.

Prerequisites

  • @hubspot/api-client installed
  • Access to application logs
  • HUBSPOT_ACCESS_TOKEN environment variable set

Instructions

Step 1: Create Debug Bundle Script

bash
#!/bin/bash
# hubspot-debug-bundle.sh

BUNDLE_DIR="hubspot-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== HubSpot Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

Step 2: Collect Environment and SDK Info

bash
echo "--- Runtime ---" >> "$BUNDLE_DIR/summary.txt"
node --version >> "$BUNDLE_DIR/summary.txt" 2>&1
npm --version >> "$BUNDLE_DIR/summary.txt" 2>&1
echo "HUBSPOT_ACCESS_TOKEN: ${HUBSPOT_ACCESS_TOKEN:+[SET]}" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# SDK version
echo "--- @hubspot/api-client ---" >> "$BUNDLE_DIR/summary.txt"
npm list @hubspot/api-client 2>/dev/null >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

Step 3: Test API Connectivity and Rate Limits

bash
echo "--- API Connectivity ---" >> "$BUNDLE_DIR/summary.txt"

# Test the API and capture headers
curl -sI https://api.hubapi.com/crm/v3/objects/contacts?limit=1 \
  -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}" \
  > "$BUNDLE_DIR/api-headers.txt" 2>&1

# Extract key info
echo "HTTP Status: $(head -1 "$BUNDLE_DIR/api-headers.txt")" >> "$BUNDLE_DIR/summary.txt"
grep -i "x-hubspot-ratelimit" "$BUNDLE_DIR/api-headers.txt" >> "$BUNDLE_DIR/summary.txt"
grep -i "x-request-id" "$BUNDLE_DIR/api-headers.txt" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# Test specific endpoints
for endpoint in contacts companies deals tickets; do
  STATUS=$(curl -so /dev/null -w "%{http_code}" \
    "https://api.hubapi.com/crm/v3/objects/${endpoint}?limit=1" \
    -H "Authorization: Bearer ${HUBSPOT_ACCESS_TOKEN}")
  echo "${endpoint}: HTTP ${STATUS}" >> "$BUNDLE_DIR/summary.txt"
done
echo "" >> "$BUNDLE_DIR/summary.txt"

# Check scopes via token info
echo "--- Token Info ---" >> "$BUNDLE_DIR/summary.txt"
curl -s "https://api.hubapi.com/oauth/v1/access-tokens/${HUBSPOT_ACCESS_TOKEN}" \
  2>/dev/null | jq '{user: .user, hub_id: .hub_id, scopes: .scopes, token_type: .token_type}' \
  >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "Token info unavailable (private app tokens)" >> "$BUNDLE_DIR/summary.txt"

Step 4: Collect Application Logs (Redacted)

bash
echo "--- Recent Logs (redacted) ---" >> "$BUNDLE_DIR/summary.txt"

# Collect recent HubSpot-related errors from application logs
if [ -f "logs/app.log" ]; then
  grep -i "hubspot\|hubapi\|crm/v3" logs/app.log 2>/dev/null | tail -100 \
    | sed -E 's/pat-[a-z0-9-]+/[REDACTED_TOKEN]/g' \
    | sed -E 's/"email":"[^"]+/"email":"[REDACTED]/g' \
    > "$BUNDLE_DIR/logs-redacted.txt"
fi

# Capture correlationIds from recent errors
grep -oP '"correlationId":"[^"]+"' logs/app.log 2>/dev/null | sort -u \
  > "$BUNDLE_DIR/correlation-ids.txt"

# Redact all secrets from config
if [ -f ".env" ]; then
  sed 's/=.*/=***REDACTED***/' .env > "$BUNDLE_DIR/config-redacted.txt"
fi

Step 5: Package and Verify

bash
# Check HubSpot status page
echo "--- HubSpot Status ---" >> "$BUNDLE_DIR/summary.txt"
curl -s https://status.hubspot.com/api/v2/summary.json 2>/dev/null \
  | jq '{status: .status.description, incidents: [.incidents[] | {name, status}]}' \
  >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "Status page unreachable" >> "$BUNDLE_DIR/summary.txt"

# Package
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo ""
echo "Bundle created: $BUNDLE_DIR.tar.gz"
echo "REVIEW FOR SENSITIVE DATA BEFORE SHARING"

Programmatic Debug Info

typescript
import * as hubspot from '@hubspot/api-client';

async function collectHubSpotDiagnostics() {
  const client = new hubspot.Client({
    accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
  });

  const diagnostics: Record<string, any> = {
    timestamp: new Date().toISOString(),
    sdkVersion: require('@hubspot/api-client/package.json').version,
    nodeVersion: process.version,
  };

  // Test each CRM object type
  const objectTypes = ['contacts', 'companies', 'deals', 'tickets'];
  for (const objType of objectTypes) {
    try {
      const start = Date.now();
      await client.apiRequest({
        method: 'GET',
        path: `/crm/v3/objects/${objType}?limit=1`,
      });
      diagnostics[objType] = { status: 'OK', latencyMs: Date.now() - start };
    } catch (error: any) {
      diagnostics[objType] = {
        status: 'ERROR',
        code: error.code || error.statusCode,
        message: error.body?.message || error.message,
        correlationId: error.body?.correlationId,
      };
    }
  }

  return diagnostics;
}

Output

  • hubspot-debug-YYYYMMDD-HHMMSS.tar.gz archive containing:
    • summary.txt -- environment, SDK version, API status, rate limits
    • api-headers.txt -- raw HTTP response headers
    • correlation-ids.txt -- unique error correlation IDs
    • logs-redacted.txt -- recent logs with secrets removed
    • config-redacted.txt -- configuration (values masked)

Error Handling

Item Purpose Included
SDK version Version-specific bugs Yes
HTTP status per object Scope/permission issues Yes
Rate limit headers Throttling diagnosis Yes
Correlation IDs HubSpot support reference Yes
HubSpot status page Platform outage detection Yes

Examples

What to Redact Before Sharing

ALWAYS REDACT:

  • Access tokens (start with pat- or JWT)
  • Email addresses and phone numbers
  • Company names from test data
  • Portal IDs (unless sharing with HubSpot support)

Safe to Include:

  • Error messages and categories
  • Correlation IDs (HubSpot support needs these)
  • HTTP status codes
  • SDK/runtime versions
  • Rate limit remaining counts

Resources

Next Steps

For rate limit issues, see hubspot-rate-limits.

Expand your agent's capabilities with these related and highly-rated skills.

Didn't find tool you were looking for?

Be as detailed as possible for better results