hubspot-debug-bundle

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

#!/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

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

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)

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

# 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

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

• HubSpot Support Portal
• HubSpot Status Page
• Error Handling Guide

Next Steps

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