Clerk Debug BundleSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: clerk-debug-bundle
description: 'Collect comprehensive debug information for Clerk issues.

  Use when troubleshooting complex problems, preparing support tickets,

  or diagnosing intermittent issues.

  Trigger with phrases like "clerk debug", "clerk diagnostics",

  "clerk support ticket", "clerk troubleshooting".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(node:*), Grep
version: 1.15.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- clerk
- debugging
compatibility: Designed for Claude Code
---
# Clerk Debug Bundle

## Current State

!`node --version 2>/dev/null || echo 'N/A'`
!`npm list @clerk/nextjs @clerk/clerk-react @clerk/express 2>/dev/null | grep clerk || echo 'No Clerk packages found'`

## Overview

Collect all necessary debug information for Clerk troubleshooting and support tickets. Generates an environment report, runtime health check, client-side debug panel, and support bundle.

## Prerequisites

- Clerk SDK installed
- Access to application logs
- Browser with developer tools

## Instructions

### Step 1: Environment Debug Script

```typescript
// scripts/clerk-debug.ts
import { createClerkClient } from '@clerk/backend'

async function collectDebugInfo() {
  const info: Record<string, any> = {
    timestamp: new Date().toISOString(),
    nodeVersion: process.version,
    platform: process.platform,
    env: {
      hasPK: !!process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
      hasSK: !!process.env.CLERK_SECRET_KEY,
      pkPrefix: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY?.slice(0, 8) + '...',
      nodeEnv: process.env.NODE_ENV,
    },
  }

  // Test API connectivity
  try {
    const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY! })
    const users = await clerk.users.getUserList({ limit: 1 })
    info.apiConnectivity = { status: 'ok', userCount: users.totalCount }
  } catch (err: any) {
    info.apiConnectivity = { status: 'error', message: err.message, code: err.status }
  }

  // Check package versions
  try {
    const pkg = require('./package.json')
    info.packages = Object.entries(pkg.dependencies || {})
      .filter(([k]) => k.includes('clerk'))
      .reduce((acc, [k, v]) => ({ ...acc, [k]: v }), {})
  } catch {
    info.packages = 'Could not read package.json'
  }

  console.log(JSON.stringify(info, null, 2))
  return info
}

collectDebugInfo()
```

Run with:

```bash
npx tsx scripts/clerk-debug.ts
```

### Step 2: Runtime Health Check Endpoint

```typescript
// app/api/clerk-health/route.ts
import { auth, clerkClient } from '@clerk/nextjs/server'

export async function GET() {
  const checks: Record<string, { status: string; detail?: string }> = {}

  // Check 1: SDK loaded
  checks.sdk = { status: 'ok', detail: 'Clerk SDK loaded' }

  // Check 2: Auth function works
  try {
    const { userId } = await auth()
    checks.auth = { status: 'ok', detail: userId ? `Authenticated as ${userId}` : 'Not authenticated (expected for health check)' }
  } catch (err: any) {
    checks.auth = { status: 'error', detail: err.message }
  }

  // Check 3: Backend API connectivity
  try {
    const client = await clerkClient()
    await client.users.getUserList({ limit: 1 })
    checks.backendApi = { status: 'ok', detail: 'API reachable' }
  } catch (err: any) {
    checks.backendApi = { status: 'error', detail: err.message }
  }

  // Check 4: Environment variables
  checks.envVars = {
    status: process.env.CLERK_SECRET_KEY ? 'ok' : 'error',
    detail: process.env.CLERK_SECRET_KEY ? 'Secret key configured' : 'CLERK_SECRET_KEY missing',
  }

  const allOk = Object.values(checks).every((c) => c.status === 'ok')
  return Response.json({ healthy: allOk, checks }, { status: allOk ? 200 : 503 })
}
```

### Step 3: Client-Side Debug Component

```typescript
'use client'
import { useAuth, useUser, useSession } from '@clerk/nextjs'
import { useState } from 'react'

export function ClerkDebugPanel() {
  const { userId, isLoaded: authLoaded, getToken } = useAuth()
  const { user, isLoaded: userLoaded } = useUser()
  const { session } = useSession()
  const [tokenPreview, setTokenPreview] = useState<string | null>(null)

  if (process.env.NODE_ENV === 'production') return null // Hide in prod

  const inspectToken = async () => {
    const token = await getToken()
    if (token) {
      const payload = JSON.parse(atob(token.split('.')[1]))
      setTokenPreview(JSON.stringify(payload, null, 2))
    }
  }

  return (
    <details style={{ position: 'fixed', bottom: 10, right: 10, background: '#1a1a2e', color: '#eee', padding: 12, borderRadius: 8, fontSize: 12, zIndex: 9999 }}>
      <summary>Clerk Debug</summary>
      <pre>
        Auth loaded: {String(authLoaded)}{'\n'}
        User loaded: {String(userLoaded)}{'\n'}
        User ID: {userId || 'null'}{'\n'}
        Email: {user?.primaryEmailAddress?.emailAddress || 'N/A'}{'\n'}
        Session ID: {session?.id || 'null'}{'\n'}
        Session status: {session?.status || 'N/A'}{'\n'}
        Last active: {session?.lastActiveAt ? new Date(session.lastActiveAt).toISOString() : 'N/A'}
      </pre>
      <button onClick={inspectToken}>Inspect JWT</button>
      {tokenPreview && <pre>{tokenPreview}</pre>}
    </details>
  )
}
```

### Step 4: Request Debug Middleware

```typescript
// middleware.ts — add debug logging (development only)
import { clerkMiddleware } from '@clerk/nextjs/server'

export default clerkMiddleware(async (auth, req) => {
  if (process.env.CLERK_DEBUG === 'true') {
    const { userId, sessionId } = await auth()
    console.log(`[Clerk Debug] ${req.method} ${req.nextUrl.pathname}`, {
      userId: userId || 'anonymous',
      sessionId: sessionId?.slice(0, 8) || 'none',
      cookies: req.cookies.getAll().map((c) => c.name).filter((n) => n.startsWith('__clerk')),
    })
  }
})
```

### Step 5: Generate Support Bundle

```bash
#!/bin/bash
# scripts/clerk-support-bundle.sh
set -euo pipefail

BUNDLE_DIR="clerk-debug-$(date +%Y%m%d-%H%M%S

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.