SU

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.zip

Installs 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.
73 charsno explicit “when” trigger
Beginner

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

You give it
Supabase project environment variables and configuration
You get back
A redacted diagnostic bundle containing connectivity, auth, Realtime, Storage, and RLS status

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-js v2 installed in the project
  • Supabase CLI installed (npm install --save-dev supabase or npx supabase)
  • Environment variables set: SUPABASE_URL and SUPABASE_ANON_KEY (minimum); SUPABASE_SERVICE_ROLE_KEY for full diagnostics
  • Project linked and target verified before approved CLI diagnostics
  • An explicitly approved existing diagnostic table with an id column, selected through SUPABASE_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:

FileContents
cli-status.txtLocal Supabase stack status (services, ports, URLs)
table-sizes.txtAll tables with row counts and disk usage
index-usage.txtIndex scan frequency — unused indexes are candidates for removal
cache-hit.txtBuffer cache and index cache hit ratios
seq-scans.txtSequential-scan observations; not proof of missing indexes
long-running-queries.txtCaptured long-running-query inspection output; check its exit status
bloat.txtTable and index bloat percentages
replication-slots.txtCaptured replication-slot inspection output; check its exit status
inspect-status.tsvPer-inspection exit statuses; failures remain failed observations
platform-status.jsonPublished platform-status observation or

Content truncated.

Prerequisites

Node.js 18+ with @supabase/supabase-js v2 installedSupabase CLI installedSUPABASE_URL and SUPABASE_ANON_KEY environment variablesProject linked via supabase link --project-ref <ref>

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.

SkillInstallsUpdatedSafetyDifficulty
supabase-debug-bundle (this skill)14moCautionBeginner
redis-inspect610moReviewBeginner
optimizing-performance15moReviewIntermediate
semaphore-third-party-licenses05moReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

More by jeremylongshore

View all by jeremylongshore →

analyzing-logs

jeremylongshore

Analyze application logs to detect performance issues, identify error patterns, and improve stability by extracting key insights.

14123

ollama-setup

jeremylongshore

Configure auto-configure Ollama when user needs local LLM deployment, free AI alternatives, or wants to eliminate hosted API costs. Trigger phrases: "install ollama", "local AI", "free LLM", "self-hosted AI", "replace OpenAI", "no API costs". Use when appropriate context detected. Trigger with relevant phrases based on skill purpose.

1167

backtesting-trading-strategies

jeremylongshore

Backtest crypto and traditional trading strategies against historical data. Calculates performance metrics (Sharpe, Sortino, max drawdown), generates equity curves, and optimizes strategy parameters. Use when user wants to test a trading strategy, validate signals, or compare approaches. Trigger with phrases like "backtest strategy", "test trading strategy", "historical performance", "simulate trades", "optimize parameters", or "validate signals".

1071

generating-database-seed-data

jeremylongshore

Process this skill enables AI assistant to generate realistic test data and database seed scripts for development and testing environments. it uses faker libraries to create realistic data, maintains relational integrity, and allows configurable data volumes. u... Use when working with databases or data models. Trigger with phrases like 'database', 'query', or 'schema'.

1033

cursor-codebase-indexing

jeremylongshore

Execute set up and optimize Cursor codebase indexing. Triggers on "cursor index setup", "codebase indexing", "index codebase", "cursor semantic search". Use when working with cursor codebase indexing functionality. Trigger with phrases like "cursor codebase indexing", "cursor indexing", "cursor".

885

testing-mobile-apps

jeremylongshore

Execute mobile app testing on iOS and Android devices/simulators. Use when performing specialized testing. Trigger with phrases like "test mobile app", "run iOS tests", or "validate Android functionality".

810

Search skills

Search the agent skills registry