supabase-debug-bundle
Automates the collection of Supabase diagnostic bundles, including connection and auth logs, for support escalation.
Install
mkdir -p .claude/skills/supabase-debug-bundle && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/6023" && unzip -o skill.zip -d .claude/skills/supabase-debug-bundle && rm skill.zipInstalls to .claude/skills/supabase-debug-bundle
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Collect Supabase diagnostic info for troubleshooting and support tickets.Key capabilities
- →Collect Supabase diagnostic information
- →Test Supabase connectivity to REST and Auth endpoints
- →Probe Realtime, Storage, and RLS subsystems
- →Package diagnostics into a single archive
- →Identify SDK and CLI versions
How it works
The skill collects diagnostic data by testing various Supabase services and packaging the results into an archive. It checks SDK versions and environment variables.
Inputs & outputs
When to use supabase-debug-bundle
- →Debug Supabase connection failures
- →Prepare diagnostic logs for support tickets
- →Audit Supabase RLS policy configurations
- →Verify Realtime and Storage service status
About this skill
Supabase Debug Bundle
Overview
Collect approved diagnostic observations into a local candidate bundle. Record query/authentication outcomes and inconclusive results without claiming complete service-health or RLS verification. Minimize and sanitize the evidence, then obtain owner review before any sharing with support.
Manual Environment Diagnostics
These commands are shown for an operator to run after approval, not executed when the skill loads. Use the project's installed CLI; a missing dependency is not a successful check.
node --version
npx supabase --version
npm list @supabase/supabase-js
Prerequisites
- Node.js 22+ with
@supabase/supabase-jsv2 installed in the project - Supabase CLI installed (
npm install --save-dev supabaseornpx supabase) - Environment variables set:
SUPABASE_URLandSUPABASE_ANON_KEY(minimum);SUPABASE_SERVICE_ROLE_KEYfor full diagnostics - Project linked and target verified before approved CLI diagnostics
- An explicitly approved existing diagnostic table with an
idcolumn, selected throughSUPABASE_DIAGNOSTIC_TABLE; no automatic table discovery or creation
Instructions
Step 1: Gather Environment and Connectivity
Collect SDK version, project URL, key type, and test basic connectivity against the REST and Auth endpoints.
import { createClient } from '@supabase/supabase-js'
const url = process.env.SUPABASE_URL!
const anonKey = process.env.SUPABASE_ANON_KEY!
const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY
// Identify which key is in use
const keyType = serviceKey ? 'service_role' : 'anon'
const supabase = createClient(url, serviceKey ?? anonKey, {
auth: { autoRefreshToken: false, persistSession: false }
})
const diagnostics: Record<string, unknown> = {}
// 1a — SDK + environment
diagnostics.environment = {
supabase_js_version: require('@supabase/supabase-js/package.json').version,
node_version: process.version,
project_url: url.replace(/https:\/\/([^.]+)\..*/, 'https://$1.***'),
key_type: keyType,
timestamp: new Date().toISOString(),
}
// 1b — REST API connectivity
const restStart = Date.now()
const restRes = await fetch(`${url}/rest/v1/`, {
headers: { apikey: anonKey, Authorization: `Bearer ${anonKey}` },
})
diagnostics.rest_api = {
status: restRes.status,
latency_ms: Date.now() - restStart,
ok: restRes.ok,
}
// 1c — Local auth storage is not an Auth-server availability/identity check.
const { data: sessionData, error: sessionErr } = await supabase.auth.getSession()
diagnostics.auth_storage = {
status: sessionErr ? 'local_storage_error' : 'local_storage_read',
has_session: !!sessionData?.session,
identity_verified: false,
}
// 1d — Query only an approved table; never turn a missing-table error into success.
const probeTable = process.env.SUPABASE_DIAGNOSTIC_TABLE
if (!probeTable) {
diagnostics.database = { status: 'not_run', detail: 'No approved diagnostic table' }
} else {
const dbStart = Date.now()
const { error } = await supabase.from(probeTable).select('id', { head: true }).limit(1)
diagnostics.database = {
status: error ? 'query_failed' : 'query_accepted',
error_code: error?.code ?? null,
latency_ms: Date.now() - dbStart,
scope: 'approved table only; not overall health or RLS verification',
}
}
console.log(JSON.stringify(diagnostics, null, 2))
What to check: Record the actual REST status. Local session storage is not a verified identity or platform-health signal. A successful table probe establishes only that approved query; missing tables (42P01 or PGRST205), authorization failures, and all other returned errors remain failures. Provision or review the diagnostic table separately; do not fabricate a health RPC.
Step 2: Test Realtime, Storage, and RLS
Probe the three subsystems that cause the most support tickets.
// 2a — Realtime subscription observation with checked channel cleanup
const channel = supabase.channel('debug-probe')
let timeout: ReturnType<typeof setTimeout> | undefined
let realtimeResult: Record<string, unknown>
try {
realtimeResult = await new Promise<Record<string, unknown>>((resolve) => {
timeout = setTimeout(() => {
resolve({ status: 'timeout', detail: 'No SUBSCRIBED event within 5s' })
}, 5000)
channel.subscribe((status) => {
if (status === 'SUBSCRIBED') {
resolve({ status: 'ok', detail: 'Channel subscribed successfully' })
} else if (status === 'CHANNEL_ERROR') {
resolve({ status: 'error', detail: 'CHANNEL_ERROR on subscribe' })
}
})
})
} finally {
if (timeout !== undefined) clearTimeout(timeout)
const cleanup = await supabase.removeChannel(channel)
if (cleanup !== 'ok') throw new Error('Realtime probe cleanup failed')
}
diagnostics.realtime = realtimeResult
// 2b — Storage bucket listing
const { data: buckets, error: storageErr } = await supabase.storage.listBuckets()
diagnostics.storage = {
status: storageErr ? `error: ${storageErr.message}` : 'ok',
bucket_count: buckets?.length ?? 0,
buckets: buckets?.map((b) => ({ name: b.name, public: b.public })) ?? [],
}
// 2c — Counts are observations, not an RLS verdict. Both probes require approval.
if (serviceKey && probeTable) {
const anonClient = createClient(url, anonKey, {
auth: { autoRefreshToken: false, persistSession: false },
})
const [anonResult, adminResult] = await Promise.all([
anonClient.from(probeTable).select('id', { count: 'exact', head: true }),
supabase.from(probeTable).select('id', { count: 'exact', head: true }),
])
diagnostics.rls_comparison = {
status: anonResult.error || adminResult.error ? 'query_failed' : 'inconclusive',
anon_error_code: anonResult.error?.code ?? null,
admin_error_code: adminResult.error?.code ?? null,
anon_visible_rows: anonResult.count,
admin_visible_rows: adminResult.count,
scope: 'Counts alone cannot establish RLS status or correctness',
}
} else {
diagnostics.rls_comparison = { status: 'not_run', detail: 'Requires approved table and admin probe' }
}
What to check: Realtime should reach SUBSCRIBED within 5 seconds. Storage should list buckets without error. Equal or different counts are inconclusive: empty tables, grants, data, and policy scope can all affect results. Separately authorize SQL catalog inspection and seeded multi-user access tests; information_schema is not assumed to be exposed as a Data API table.
Step 3: Collect Database Health and Package the Bundle
Collect only approved database statistics and platform-status evidence. The script below creates a local candidate archive; its example masking is incomplete and does not approve the result for export.
#!/bin/bash
set -euo pipefail
BUNDLE_DIR="supabase-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"
# 3a — Supabase CLI status (local dev)
npx supabase status > "$BUNDLE_DIR/cli-status.txt" 2>&1 || echo "CLI status unavailable (not linked or no local dev)" > "$BUNDLE_DIR/cli-status.txt"
# 3b — Approved database inspections; preserve individual exit statuses.
# A captured output file can contain an error, not a successful observation.
STATUS_FILE="$BUNDLE_DIR/inspect-status.tsv"
printf 'inspection\texit_status\n' > "$STATUS_FILE"
for inspection in table-sizes index-usage cache-hit seq-scans long-running-queries bloat replication-slots; do
if npx supabase inspect db "$inspection" > "$BUNDLE_DIR/$inspection.txt" 2>&1; then
probe_status=0
else
probe_status=$?
fi
printf '%s\t%s\n' "$inspection" "$probe_status" >> "$STATUS_FILE"
done
# Fail if receipt creation fails; nonzero probe statuses remain explicit partial evidence.
cat "$STATUS_FILE"
# 3c — Platform status page
curl -sf https://status.supabase.com/api/v2/status.json \
| python3 -m json.tool > "$BUNDLE_DIR/platform-status.json" 2>/dev/null \
|| echo '{"error": "Could not reach status.supabase.com"}' > "$BUNDLE_DIR/platform-status.json"
# 3d — Partial example masking only; inspect and sanitize the candidate manually
find "$BUNDLE_DIR" -type f -exec sed -i \
-e 's/eyJ[A-Za-z0-9_-]\{20,\}\(\.[A-Za-z0-9_-]*\)*/[JWT_REDACTED]/g' \
-e 's/sbp_[A-Za-z0-9]\{20,\}/[SBP_KEY_REDACTED]/g' \
-e 's/[A-Za-z0-9._%+-]\+@[A-Za-z0-9.-]\+\.[A-Za-z]\{2,\}/[EMAIL_REDACTED]/g' {} +
# 3e — Local candidate only; owner-reviewed minimization/sanitization required before sharing
tar czf "${BUNDLE_DIR}.tar.gz" "$BUNDLE_DIR"
echo "Debug bundle created: ${BUNDLE_DIR}.tar.gz"
echo "Contents:"
ls -lh "$BUNDLE_DIR"/
What to check: Inspect inspect-status.tsv first: a nonzero exit status means that inspection failed, even when an output file was archived. Treat the bundle as partial evidence. Cache ratios, estimated bloat, and sequential scans depend on workload, table size, measurement interval, and query plans; they do not by themselves establish memory pressure, a missing index, or a need for VACUUM or larger compute. Review approved baselines and execution plans before proposing separately authorized remediation.
Output
The skill produces supabase-debug-YYYYMMDD-HHMMSS.tar.gz containing:
| File | Contents |
|---|---|
cli-status.txt | Local Supabase stack status (services, ports, URLs) |
table-sizes.txt | All tables with row counts and disk usage |
index-usage.txt | Index scan frequency — unused indexes are candidates for removal |
cache-hit.txt | Buffer cache and index cache hit ratios |
seq-scans.txt | Sequential-scan observations; not proof of missing indexes |
long-running-queries.txt | Captured long-running-query inspection output; check its exit status |
bloat.txt | Table and index bloat percentages |
replication-slots.txt | Captured replication-slot inspection output; check its exit status |
inspect-status.tsv | Per-inspection exit statuses; failures remain failed observations |
platform-status.json | Published platform-status observation or |
Content truncated.
Prerequisites
How it compares
This skill automates the collection of complete Supabase diagnostic data, which is more thorough than manual checks for troubleshooting and support.
Compared to similar skills
supabase-debug-bundle side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| supabase-debug-bundle (this skill) | 1 | 4mo | Caution | Beginner |
| redis-inspect | 6 | 10mo | Review | Beginner |
| optimizing-performance | 1 | 5mo | Review | Intermediate |
| semaphore-third-party-licenses | 0 | 5mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by jeremylongshore
View all by jeremylongshore →You might also like
redis-inspect
civitai
Inspect Redis cache keys, values, and TTLs for debugging. Supports both main cache and system cache. Use for debugging cache issues, checking cached values, and monitoring cache state. Read-only by default.
optimizing-performance
CloudAI-X
Analyzes and optimizes application performance across frontend, backend, and database layers. Use when diagnosing slowness, improving load times, optimizing queries, reducing bundle size, or when asked about performance issues.
semaphore-third-party-licenses
semaphoreui
>
hiddenroom-supabase
cuvo1903-ctrl
Hidden Room Supabase backend skill for migrations, generated database types, Edge Functions, RLS policies, auth/profile sync, storage buckets, Stripe integration, cloud_jobs, and database documentation. Use when editing supabase/migrations, supabase/functions, database.types.ts, or Supabase-backed f
backend-security-coder
sickn33
Expert in secure backend coding practices specializing in input validation, authentication, and API security. Use PROACTIVELY for backend security implementations or security code reviews.
supabase-common-errors
jeremylongshore
Execute diagnose and fix Supabase common errors and exceptions. Use when encountering Supabase errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "supabase error", "fix supabase", "supabase not working", "debug supabase".