insforge-debug

Original：🇺🇸 English
Not Translated

Use this skill when encountering errors, bugs, performance issues, or unexpected behavior in an InsForge project — from frontend SDK errors to backend infrastructure problems. Trigger on: SDK returning error objects, HTTP 4xx/5xx responses, edge function failures or timeouts, slow database queries, authentication/authorization failures, realtime channel issues, backend performance degradation (high CPU/memory/slow responses), edge function deploy failures, or frontend Vercel deploy failures. This skill guides diagnostic command execution to locate problems; it does not provide fix suggestions.

2installs
Sourceinsforge/insforge-skills
Added on

NPX Install

npx skill4agent add insforge/insforge-skills insforge-debug

SKILL.md Content

InsForge Debug

Diagnose problems in InsForge projects — from frontend SDK errors to backend infrastructure issues. This skill helps you locate problems by running the right commands and surfacing logs/status. It does NOT suggest fixes; hand the diagnostic output to the developer or their agent for repair decisions.
Always use 
npx @insforge/cli
 — never install the CLI globally.

Quick Triage

Match the symptom to a scenario, then follow that scenario's steps.
SymptomScenario
SDK returns 
{ data: null, error: {...} }
#1 SDK Error
HTTP 400 / 401 / 403 / 404 / 429 / 500#2 HTTP Status Code
Function throws or times out#3 Edge Function Failure
Query slow or hangs#4 Database Slow
Login fails / token expired / RLS denied#5 Auth Failure
Channel won't connect / messages missing#6 Realtime Issues
High CPU/memory, all responses slow#7 Backend Performance
functions deploy
fails		#8 Function Deploy
deployments deploy
fails / Vercel error		#9 Frontend Deploy

Scenario 1: SDK Returns Error Object

Symptoms: SDK call returns 
{ data: null, error: { code, message, details } }
. PostgREST error codes like 
PGRST301
, 
PGRST204
, etc.
Steps:
  1. Read the error object — extract 
    code
    , 
    message
    , 
    details
    from the SDK response.
  2. Check aggregated error logs to find matching backend errors:
bash
npx @insforge/cli diagnose logs
  1. Based on the error code prefix, drill into the relevant log source:
Error patternLog sourceCommand
PGRST*
(PostgREST)		postgREST.logs
npx @insforge/cli logs postgREST.logs --limit 50
Database/SQL errorspostgres.logs
npx @insforge/cli logs postgres.logs --limit 50
Generic 500 / server errorinsforge.logs
npx @insforge/cli logs insforge.logs --limit 50
  1. If the error is DB-related, check database health for additional context:
bash
npx @insforge/cli diagnose db --check connections,locks,slow-queries
Information gathered: Error code, backend log entries around the error timestamp, database health status.

Scenario 2: HTTP Status Code Anomaly

Symptoms: API calls return 400, 401, 403, 404, 429, or 500.
Steps:
  1. Identify the status code from the response.
  2. Follow the path for that status code:
StatusWhat to checkCommand
400Request payload/params malformed
npx @insforge/cli logs postgREST.logs --limit 50
401Auth token missing or expired
npx @insforge/cli logs insforge.logs --limit 50
403RLS policy or permission denied
npx @insforge/cli logs insforge.logs --limit 50
404Endpoint or resource doesn't exist
npx @insforge/cli metadata --json
429Rate limit hit — no backend logs recordedSee 429 note below
500Server-side error
npx @insforge/cli diagnose logs
  1. For 500 errors, also check aggregate error logs across all sources:
bash
npx @insforge/cli diagnose logs
  1. 429 Rate Limit: The backend does not log 429 responses and does not return 
    Retry-After
    or 
    X-RateLimit-*
    headers. Checking logs will not help. Instead:
    • Review client code for high-frequency request patterns: loops without throttling, missing debounce, retry without exponential backoff, or parallel calls that could be batched.
    • Check overall backend load to see if the system is under heavy traffic:
      bash
      npx @insforge/cli diagnose metrics --range 1h
    • A 429 status confirms the request was rate-limited. The fix is always on the client side: reduce request frequency, add backoff/debounce, or batch operations.
Information gathered: Status code context, relevant log entries, request/response details from logs. For 429: client-side request patterns and backend load metrics.

Scenario 3: Edge Function Execution Failure/Timeout

Symptoms: 
functions invoke
returns error, function times out, or throws runtime exception.
Steps:
  1. Check function execution logs:
bash
npx @insforge/cli logs function.logs --limit 50
  1. Verify the function exists and is active:
bash
npx @insforge/cli functions list
  1. Inspect the function source for obvious issues:
bash
npx @insforge/cli functions code <slug>
Information gathered: Function runtime errors, function status, source code, EC2 resource metrics.

Scenario 4: Database Query Slow or Unresponsive

Symptoms: Queries take too long, hang indefinitely, or connection pool is exhausted.
Steps:
  1. Check database health — slow queries, active connections, locks:
bash
npx @insforge/cli diagnose db --check slow-queries,connections,locks
  1. Check postgres logs for query errors or warnings:
bash
npx @insforge/cli logs postgres.logs --limit 50
  1. Check index usage and table bloat:
bash
npx @insforge/cli diagnose db --check index-usage,bloat,cache-hit,size
  1. If the whole system feels slow, check EC2 instance metrics:
bash
npx @insforge/cli diagnose metrics --range 1h
Information gathered: Slow query details, connection pool state, lock contention, index efficiency, table bloat, cache hit ratio, EC2 resource usage.

Scenario 5: Authentication/Authorization Failure

Symptoms: Login fails, signup errors, token expired, OAuth callback error, RLS policy denies access.
Steps:
  1. Check insforge.logs for auth-related errors (login failures, token issues, OAuth errors):
bash
npx @insforge/cli logs insforge.logs --limit 50
  1. Check postgREST.logs for RLS policy violations:
bash
npx @insforge/cli logs postgREST.logs --limit 50
  1. Verify the project's auth configuration:
bash
npx @insforge/cli metadata --json
  1. If RLS suspected, inspect current policies:
bash
npx @insforge/cli db policies
Information gathered: Auth error details, RLS violation logs, auth configuration state, active RLS policies.

Scenario 6: Realtime Channel Issues

Symptoms: WebSocket won't connect, channel subscription fails, messages not received or lost.
Steps:
  1. Check insforge.logs for realtime/WebSocket errors:
bash
npx @insforge/cli logs insforge.logs --limit 50
  1. Verify the channel pattern exists and is enabled:
bash
npx @insforge/cli db query "SELECT pattern, description, enabled FROM realtime.channels"
  1. If access is restricted, check RLS on realtime tables:
bash
npx @insforge/cli db policies
  1. If the issue is widespread (all channels affected), check overall backend health:
bash
npx @insforge/cli diagnose
Information gathered: WebSocket error logs, channel configuration, realtime RLS policies, overall backend health.

Scenario 7: Backend Performance Degradation

Symptoms: All responses slow, high latency, intermittent failures across the board.
Steps:
  1. Check EC2 instance metrics — CPU, memory, disk, network:
bash
npx @insforge/cli diagnose metrics --range 1h
  1. Check database health (often the bottleneck):
bash
npx @insforge/cli diagnose db
  1. Check aggregate error logs:
bash
npx @insforge/cli diagnose logs
  1. Check advisor for known critical issues:
bash
npx @insforge/cli diagnose advisor --severity critical
Information gathered: CPU/memory/disk/network metrics (current and trend), database health, error log summary, advisor warnings.

Scenario 8: Edge Function Deploy Failure

Symptoms: 
functions deploy <slug>
command fails, function not appearing in the list after deploy.
Steps:
  1. Re-run the deploy command and capture the error output:
bash
npx @insforge/cli functions deploy <slug>
  1. Check deployment-related errors:
bash
npx @insforge/cli logs function-deploy.logs --limit 50
  1. Verify whether the function exists in the list:
bash
npx @insforge/cli functions list
Information gathered: Deploy command error output, function deployment logs, function list status, backend error logs.

Scenario 9: Frontend (Vercel) Deploy Failure

Symptoms: 
deployments deploy
command fails, deployment status shows error, Vercel build errors.
Steps:
  1. Check recent deployment attempts:
bash
npx @insforge/cli deployments list
  1. Get the status and error details for the failed deployment:
bash
npx @insforge/cli deployments status <id> --json
The 
--json
output includes a 
metadata
object with Vercel-specific context: 
target
, 
fileCount
, 
projectId
, 
startedAt
, 
envVarKeys
, 
webhookEventType
(e.g., 
deployment.succeeded
or 
deployment.error
), etc. This metadata captures the full deployment context and can be used for debugging or AI-assisted investigation.
  1. Verify the local build succeeds before investigating further:
bash
npm run build
Information gathered: Deployment history, deployment metadata (Vercel context, status, webhook events), local build output, backend deployment API logs.

Command Quick Reference

Logs

bash
npx @insforge/cli logs <source> [--limit <n>]
SourceDescription
insforge.logs
Main backend logs
postgREST.logs
PostgREST API layer logs
postgres.logs
PostgreSQL database logs
function.logs
Edge function execution logs
function-deploy.logs
Edge function deployment logs
Source names are case-insensitive.

Diagnostics

bash
# Full health report (all checks)
npx @insforge/cli diagnose

# EC2 instance metrics (CPU, memory, disk, network)
npx @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] [--metrics <list>]

# Advisor scan results
npx @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] [--limit <n>]

# Database health checks
npx @insforge/cli diagnose db [--check <checks>]
# checks: connections, slow-queries, bloat, size, index-usage, locks, cache-hit (default: all)

# Aggregate error logs from all sources
npx @insforge/cli diagnose logs [--source <name>] [--limit <n>]

Supporting Commands

bash
# Project metadata (auth config, tables, buckets, functions, etc.)
npx @insforge/cli metadata --json

# Edge functions
npx @insforge/cli functions list
npx @insforge/cli functions code <slug>

# Secrets
npx @insforge/cli secrets list [--all]
npx @insforge/cli secrets get <key>
npx @insforge/cli secrets add <key> <value> [--reserved] [--expires <ISO date>]

# Database
npx @insforge/cli db policies
npx @insforge/cli db query "<sql>"

# Deployments
npx @insforge/cli deployments list
npx @insforge/cli deployments status <id> --json