Insforge Debug

InsForge Debug

Diagnose problems in InsForge projects by combining the backend's observability primitives — logs, metrics, db-health, advisor, policies, metadata, error objects, deploy state, and AI assist. This skill provides:

1. A reference per debug primitive (one observability surface each — under references/) 2. Symptom Recipes (below) that name the primitive sequence for known reactive symptoms and proactive audits

Always use `npx @insforge/cli` — never install the CLI globally.

Fastest Path: AI-Assisted Triage

When the user gives a concrete description (error message, failing URL, HTTP status), hand it to the InsForge debug agent. Unlike the other primitives, this one returns suggestions, not just observations — verify the diagnosis against the primitives it cites before acting on it.

npx @insforge/cli diagnose --ai "<issue description>"

See references/ai-assisted.md for when to use this first vs when to skip, and how to verify the output.

Debug Primitives

Each primitive is one independently-queryable observability surface backed by a distinct underlying data source. Real diagnoses are compositions of primitives.

All commands run via npx @insforge/cli .... The (command) shown next to each primitive is the actual CLI command — primitive names are concept labels, not CLI subcommand names (e.g., "DB health" is diagnose db, not diagnose db-health; "Policies" is db policies, not diagnose policies).

Symptom Recipes

Each recipe is a primitive call sequence with one-line "look for X" at each step. Command syntax, flags, and deep interpretation are in the per-primitive references above.

Recipe: SDK returned { data: null, error: { code, message } }

1. error-objects — read code/message/details. If code starts with PGRST*, route by prefix using the table in the reference. 2. logs (matching source per error-objects routing) — find the error timestamp, get the full backend-side context. 3. db-health (connections, locks, slow-queries) — only if the error suggests DB issue (PostgREST timeout, lock conflict).

Recipe: HTTP 4xx/5xx response on a specific request

1. error-objects — use the HTTP status routing table to pick the log source (each status has a distinct path; 429 is special). 2. logs (right source for that status) — find the failing request line and error. 3. metrics — only for 5xx patterns spanning multiple endpoints, to confirm system-wide load issue.

Recipe: RLS access issue (403 on write, or empty result on read)

Same bug, two surfacings. Writes (INSERT / UPDATE / DELETE) fail loudly with 403. Reads (SELECT) fail silently with an empty array — PostgREST filters denied rows out instead of returning 403, so the request looks successful with zero rows. Diagnosis path is the same except step 1 only applies to the 403 variant.

1. logs (postgREST.logs) — 403 variant only: find the policy violation event with table and role context. Empty-result variant: skip — no error is logged for silently-filtered rows. 2. policies — list policies for that table; walk USING / WITH CHECK against the actual request and the JWT claim used. 3. metadata — verify auth config (which claim feeds auth.uid() / requesting_user_id(); for third-party auth like Clerk/Auth0, is the provider registered as a JWT issuer?). 4. db query (db query "<sql>") — empty-result variant only: confirm rows that should be visible actually exist by querying as service role (not as the user): npx @insforge/cli db query "SELECT id, user_id FROM <table>". Distinguishes "RLS filtered everything" from "no matching data exists".

Recipe: Login fails / OAuth callback errors / token expired

1. logs (insforge.logs) — find auth errors with timestamp and provider context. 2. metadata — verify the provider is enabled, redirect URLs match the callback URL exactly (protocol + host + path).

Recipe: Edge function runtime error / timeout

1. logs (function.logs) — get the error stack and execution context. 2. metadata — confirm the function exists and status: "active". 3. (If needed) npx @insforge/cli functions code <slug> — inspect the source for obvious issues.

Recipe: functions deploy failed

1. deploy-state (function-deploy.logs) — find the build/push error. 2. metadata — confirm whether the function ended up in the active list (partial-deploy detection).

Recipe: deployments deploy failed (Vercel)

1. deploy-state (deployments list + status <id> --json) — read status, metadata.webhookEventType, and envVarKeys. 2. Local npm run build — reproduce the same error locally for faster iteration.

Recipe: Single slow query / one endpoint slow

1. logs (postgres.logs) — find the query text and timestamp. 2. db-health (slow-queries, index-usage) — confirm it's in pg_stat_statements; check for missing index. 3. policies — if it's an RLS-gated table, verify the policy isn't adding hidden joins.

Recipe: All responses slow / high CPU/memory (active incident)

1. metrics (--range 1h) — confirm system-wide pressure (CPU / memory / disk). 2. db-health — DB is the most common bottleneck; check connections, locks, slow-queries. 3. logs (diagnose logs aggregate) — error patterns across sources at the spike timestamp. 4. advisor (--severity critical) — pre-existing known issues that may explain the degradation.

Recipe: Realtime channel won't connect / messages missing

1. logs (insforge.logs) — WebSocket errors and subscription failures. 2. metadata — verify the channel pattern matches what the client subscribes to, enabled: true. 3. policies — RLS on the underlying table (realtime delivers row changes; RLS gates which rows the subscriber sees).

Recipe: 429 rate limit

1. error-objects — confirm 429 status. No logs are recorded for 429s; no `Retry-After` header is returned. Don't waste time grepping logs. 2. metrics (--range 1h) — overall backend load context. 3. Fix is always client-side: debounce, batch, exponential backoff, eliminate retry loops.

Recipe: Gateway timeout (502 / 503 / 504) on a specific URL

Route by URL subsystem before drilling:

Recipe: Pre-launch / proactive audit

Requires Platform login (npx @insforge/cli login). Not available when the project is linked via `--api-key` — fall back to db-health + policies + metadata for a manual audit in that case.

1. advisor — full scan, then --severity critical first, then warnings. 2. advisor (--category security) — focus on security issues; cross-verify with policies (RLS coverage) and metadata (auth config, public buckets, secret presence). 3. advisor (--category performance) — cross-verify with db-health (slow-queries, index-usage, bloat). 4. advisor (--category health) — cross-verify with metrics (resource trends over 7d). 5. After fixes, re-run advisor and confirm isResolved: true for each addressed ruleId.

Recipe: Don't know where to start

1. ai-assisted (diagnose --ai "<error or URL>") — get a starting hypothesis. 2. Verify by re-checking the primitives the diagnosis names. Trust the primitive observations over the suggestion.

Advisor

Static-scan engine that audits the project against a rule catalog and returns issue rows. The primary primitive for proactive audits — security misconfigurations, performance regressions, and system health concerns surfaced without a specific failing request.

Command

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

Default limit: 50. Requires Platform login — not available on backends linked via `--api-key`.

Add `--json` when you need the full issue payload. Human-readable output is a 4-column table (severity / category / affectedObject / title). Fields like ruleId, description, recommendation, isResolved are only emitted by --json — without the flag, you can't read or act on the recommendation programmatically.

What you see

Each scan returns:

Scan summary — scanId, scannedAt, status, and counts by severity (critical / warning / info).

Issue rows — each issue has:

Categories

How to read

1. Start with severity: --severity critical first; critical issues block launch. 2. Group by category to keep the fix mode coherent (don't context-switch between RLS edits and index migrations). 3. `affectedObject` tells you where to fix — it names the concrete schema object. 4. `recommendation` is usually actionable as-is. Verify it makes sense (the recommendation may be generic), then apply via the appropriate primitive's tooling.

Iteration workflow

1. Scan:    diagnose advisor --severity critical --json
2. Triage:  pick one issue, read affectedObject + recommendation
3. Verify:  inspect the affected object (db query / db policies / metadata)
4. Fix:     apply the change (migration / RLS edit / secret rotation / config update)
5. Re-scan: diagnose advisor --json — confirm isResolved=true for that ruleId
6. Repeat with next critical, then warnings, then info

Boundaries

• Scans are not real-time. A new scan triggers when the platform schedules it; recommendations lag behind very recent changes. Force a fresh scan if needed.
• Recommendations are static suggestions, not auto-fixes. Always validate against current schema state before applying.
• `affectedObject` is a string, not a typed reference. It names the object but doesn't link to it — combine with metadata / policies to inspect.
• Not available when linked via `--api-key`. Requires insforge login (Platform auth).

Example

Pre-launch audit:

# Full scan, critical only first
npx @insforge/cli diagnose advisor --severity critical

# Security focus
npx @insforge/cli diagnose advisor --category security

# Performance focus (often pairs with db-health to verify)
npx @insforge/cli diagnose advisor --category performance
npx @insforge/cli diagnose db --check slow-queries,index-usage

# Re-scan after fixes
npx @insforge/cli diagnose advisor --severity critical

Frequently paired with

• policies — security category issues often name a table with missing/broken RLS policy
• metadata — security/health issues often name a configured object (bucket, secret, auth provider) whose state needs inspecting
• db-health — performance category overlaps with slow-queries / index-usage / bloat; cross-verify
• metrics — health category issues (pool exhaustion, disk fill) line up with metric trends

AI assist

The meta-primitive: hand a natural-language problem description to a backend-side LLM agent that combines the other primitives (logs, metrics, db-health, advisor, policies, metadata) on its own and returns a diagnosis plus suggested solutions.

Unlike every other primitive in this skill, `diagnose --ai` returns suggestions, not just observations. Verify before acting.

Command

npx @insforge/cli diagnose --ai "<issue description>"

The description should include: the error / failing URL / HTTP status / function slug — whatever concrete signal the user has.

When to use first

• User pasted an error, request URL, or status code and asks "why?"
• You want a fast first pass before deciding which primitive to drill into
• The problem spans multiple subsystems (frontend + backend + database) and the right starting primitive isn't obvious

When to skip

• The symptom clearly maps to one primitive (e.g., "Vercel deploy failed" → go straight to deploy-state)
• You're doing a proactive audit (no concrete error — that's advisor)
• You already know exactly which log source has the error

How to verify the output

The agent's diagnosis names primitives and observations. Re-check each:

If the verification disagrees with the diagnosis, trust the primitive observation, not the suggestion. Suggestions can be plausible-sounding but wrong (LLM may pattern-match on similar errors); raw pg_stat numbers and log lines can't lie.

Boundaries

• Returns suggestions, not just data. Different from every other primitive — treat the output as a starting hypothesis, not a verdict.
• Doesn't replace [advisor](advisor.md). Advisor surfaces issues based on a static rule catalog; --ai reasons about a specific reported symptom. They serve different goals.
• Consumes the other primitives. When this fails or seems off, fall back to the primitives directly.

Example

User pastes: "I invoked https://kttprzh4.functions.insforge.app/newton and got 508: Loop Detected (LOOP_DETECTED). Recursive requests to the same deployment cannot be processed."

npx @insforge/cli diagnose --ai "I invoked edge function https://kttprzh4.functions.insforge.app/newton, got error: 508: Loop Detected (LOOP_DETECTED)\n\nRecursive requests to the same deployment cannot be processed."

Read the diagnosis and suggestions, then verify with:

# Verify with function logs
npx @insforge/cli logs function.logs --limit 50

# Verify the function code doesn't actually call itself
npx @insforge/cli functions code newton

Frequently paired with

• All other primitives — --ai consumes them and you verify back against them. Treat AI assist as a router that points at primitives; the primitives are the ground truth.

DB health

Postgres system views (pg_stat_*, pg_locks, pg_class) exposed as named checks. The primary primitive for current database state — connection pool, query performance, lock contention, storage, index efficacy.

Command

npx @insforge/cli diagnose db [--check <checks>]

--check accepts comma-separated names. Default all. Run no-arg first when triaging unknown DB issues.

Checks

How to read

Boundaries

• Current snapshot, not history. pg_stat_* resets on Postgres restart; numbers are cumulative since last reset, not a time series.
• Doesn't show query text inline. slow-queries shows hashed query templates — get the actual SQL from logs (postgres.logs) or pg_stat_statements.query directly via db query.
• Doesn't evaluate RLS. For "which policy is making this query slow," use policies.

Example

User reports: "this one query is slow — SELECT * FROM orders WHERE user_id = ... ORDER BY created_at DESC".

# 1. Confirm it's in the slow-query log and check index usage on the table
npx @insforge/cli diagnose db --check slow-queries,index-usage

# 2. Verify no lock contention from a concurrent writer
npx @insforge/cli diagnose db --check locks

# 3. Cross-reference postgres.logs for the actual query plan / errors
npx @insforge/cli logs postgres.logs --limit 100

Frequently paired with

• logs — postgres.logs has the query text, plans, and error context behind slow-queries/locks aggregates
• policies — when slow queries are RLS-gated, the policy may be adding hidden joins
• metrics — DB pressure usually shows as EC2 CPU/memory pressure; cross-reference timestamps
• advisor — performance category often pre-flags the same issues slow-queries / index-usage would surface

Deploy state

History and per-deploy metadata for both frontend deployments (Vercel) and edge function deploys. The primary primitive for debugging what happened during a deploy — separate from runtime logs because deploy failures often never leave a runtime trace.

Commands

# Frontend (Vercel)
npx @insforge/cli deployments list
npx @insforge/cli deployments status <id> [--sync] [--json]

# Edge function deploys
npx @insforge/cli logs function-deploy.logs [--limit <n>]
npx @insforge/cli functions list

Frontend deployments

deployments list returns recent deploys with status. deployments status <id> --json returns per-deploy metadata:

--sync re-fetches from Vercel (use when the local cached status looks stale).

Edge function deploys

function-deploy.logs captures backend deploy events (compile errors, push failures, registration errors). functions list confirms the final state — if the function isn't there or status != active, the deploy didn't fully take.

How to read

For "frontend deploy failed":

1. deployments list — find the failing deploy id 2. deployments status <id> --json — read status and the metadata block; webhookEventType usually names the failure stage 3. Reproduce locally: npm run build — server deploys often surface the same error that local build would (faster to debug locally) 4. Verify envVarKeys matches what the app needs at runtime

For "function deploy failed":

1. npx @insforge/cli logs function-deploy.logs --limit 50 — find the build/push error 2. npx @insforge/cli functions list — confirm the function did or didn't make it into the active list 3. Re-run npx @insforge/cli functions deploy <slug> if needed and capture stdout for the explicit error

Boundaries

• Doesn't surface Vercel build logs inline. Detailed Vercel build output lives in the Vercel dashboard or via vercel logs; this primitive surfaces the deploy event metadata.
• Doesn't include compute service (Fly) deploy errors. For compute services use npx @insforge/cli compute events <id> (machine lifecycle); container stdout/stderr is not yet exposed.
• Distinct from runtime errors. A function with a successful deploy can still error at invoke time — that's logs function.logs, not this primitive.

Example

User reports: "I ran deployments deploy and got an error."

# 1. Get the most recent deploy id and status
npx @insforge/cli deployments list

# 2. Full metadata on the failed one
npx @insforge/cli deployments status <id> --json

# 3. Reproduce locally to see the actual build error
npm run build

User reports: "functions deploy my-handler failed."

# 1. Re-run to capture the explicit error
npx @insforge/cli functions deploy my-handler

# 2. Backend-side deploy log
npx @insforge/cli logs function-deploy.logs --limit 50

# 3. Confirm the function isn't half-deployed
npx @insforge/cli functions list

Frequently paired with

• logs — function-deploy.logs is the source; function.logs is separate (runtime, not deploy)
• metadata — verify the function ended up active after deploy

Error objects

The error envelope returned by SDK calls and HTTP responses. The entry-point primitive — almost every reactive debug starts by reading the error and routing to the right log source / primitive.

This primitive isn't a command; it's the protocol for reading what the client got back, plus the routing tables that turn an error into "look here next."

SDK error envelope

const { data, error } = await client.database.from('posts').select('*')
// error: { code: string, message: string, details?: string }

Read all three fields. code routes to the right log source; message and details provide context.

Error code → log source

HTTP status routing

429 — special case

429 responses are not logged in any source and the backend does not return Retry-After or X-RateLimit-* headers. Checking logs is useless.

What to do:

1. Read the client code that issued the request. Look for: loops without throttling, missing debounce, retry-on-failure without exponential backoff, parallel calls that could be batched. 2. Check metrics for overall backend load context — is the system being slammed? 3. The fix is always client-side: reduce frequency, add backoff/debounce, batch operations.

5xx gateway timeout (502 / 503 / 504) — route by URL subsystem

The status alone doesn't tell you which subsystem timed out. Route by the URL path:

Example

User pastes: POST /api/database/records/posts returned { code: "PGRST204", message: "Column not found" }.

1. Read code: PGRST* → PostgREST source. PGRST204 specifically means column not found — a select / columns / order / filter parameter references a column that doesn't exist on the table. 2. Read message / details to identify the offending column name. Verify the table schema with npx @insforge/cli db tables or npx @insforge/cli metadata --json. 3. Drop into postgREST.logs for the full error context if details is empty:

npx @insforge/cli logs postgREST.logs --limit 50

Frequently paired with

• logs — every code routes to a log source for the actual error context
• policies — 403 always needs policy inspection
• metadata — 404 / config-related codes need metadata to confirm the configured state
• ai-assisted — when the code is unfamiliar or the error spans subsystems, hand it to diagnose --ai

Logs

Time-stream of events emitted by each backend service. The primary primitive for finding when something failed and what the backend was doing at that moment.

Command

npx @insforge/cli logs <source> [--limit <n>]

Default limit: 20. Source names are case-insensitive (postgrest.logs works the same as postgREST.logs).

Sources

Cross-source aggregate

npx @insforge/cli diagnose logs [--source <name>] [--limit <n>]

Aggregates error-level only rows across all sources. Use first when you don't know which source the error lives in.

How to read

Each line has timestamp + source + level + message. When chasing a known-time symptom:

1. Get the approximate timestamp from the user (when did the request fail?) 2. Increase --limit until the window covers it (start 50, bump to 200 if needed) 3. Look for the level (ERROR / WARN) and message — the message usually names the failing component

For request-correlated symptoms (single failing URL), look for the request line in postgREST.logs (REST calls) or insforge.logs (auth/realtime/function dispatch) — both include the URL path.

Boundaries

• Logs are streamed, not retained forever. If the user reports something from days ago, you may not find it. State this explicitly instead of guessing.
• 429 responses are NOT logged. Rate limit hits don't appear in any source — confirm via error-objects status code and check metrics for backend load context.
• `diagnose logs` filters to errors only. For warnings or info-level activity, query the specific source directly.

Example

User reports: POST /api/database/records/posts returned 500 around 14:32.

# Aggregate first to see if the error surfaces anywhere
npx @insforge/cli diagnose logs --limit 100

# If it's a CRUD path, postgREST is the likely source
npx @insforge/cli logs postgREST.logs --limit 100

# If postgREST log shows "SQL error", drop into postgres
npx @insforge/cli logs postgres.logs --limit 100

Frequently paired with

• error-objects — start there to pick the right source from the error code/HTTP status
• db-health — when postgres.logs shows slow/locked queries, confirm with pg_stat_*
• policies — when postgREST.logs shows RLS denial, inspect which policy fired
• metadata — when logs show auth/function/channel errors, verify the configured state

Metadata

Declarative dump of the backend's configured state: auth provider config, database tables, storage buckets, edge functions, AI models, realtime channels. The primary primitive for what the project is set up to do — used to confirm configuration matches expectations, find misconfiguration, and detect drift.

Command

npx @insforge/cli metadata [--json]

--json for structured output (preferred when extracting fields for follow-up commands).

What you see

How to read

For "is this thing configured the way I think?":

Boundaries

• Configuration state, not runtime state. Tells you what's declared, not what's currently broken. A function with status: active may still be crashing on every invocation — pair with logs (function.logs).
• Doesn't show RLS policies. For RLS use policies; metadata only confirms the table exists.
• Snapshot at query time. Just-applied migrations or deploys may not yet be reflected — wait a moment and re-query if you suspect staleness.

Example

User reports: "OAuth login with Google redirects but then errors out."

# 1. Pull current auth config
npx @insforge/cli metadata --json

# 2. In the auth section, confirm:
#    - google provider enabled: true
#    - redirect URLs include the exact callback the app uses
#    (e.g., https://myapp.com/auth/callback — protocol + host + path must match)

# 3. If config looks right, check insforge.logs for the OAuth error
npx @insforge/cli logs insforge.logs --limit 50

Frequently paired with

• logs — metadata says "configured" but logs say "actually broken"; pair to distinguish config drift vs runtime failure
• policies — metadata confirms the table; policies show the RLS gating it
• advisor — security/health issues often name a configured object (bucket, secret, function) for inspection

Metrics

EC2 instance time-series telemetry: CPU, memory, disk, network. The primary primitive for confirming system-wide resource pressure vs an isolated request issue.

Command

npx @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] [--metrics <list>]

Default range: 1h.

What you see

Range selection

How to read

1. Start from baseline: what does the normal range look like for this metric? Always look at the trend, not a single point. 2. Correlate to events: spike at a specific timestamp → cross-reference logs for what was happening then. 3. Distinguish saturation vs spike:

• Sustained high = saturation → scale up or fix the load source
• Brief spike + recovery = normal burst → not actionable on its own

Boundaries

• Instance-level only. Metrics show the EC2 box's resource use, not per-request latency or per-query cost. For request-specific perf, combine with logs (postgres.logs for slow queries) and db-health.
• Doesn't explain causes. Metrics show symptoms (CPU high), not causes (which query, which function). Pair with logs or db-health for root cause.
• Edge function execution is separate. Functions run in their own runtime; their resource use isn't in EC2 metrics.

Example

User reports: "API has been slow for the last 2 hours."

# 1. Check resource pressure over the right window
npx @insforge/cli diagnose metrics --range 6h

# 2. If CPU/memory spiked at a timestamp, line it up with errors
npx @insforge/cli diagnose logs --limit 200

# 3. If DB is the bottleneck (Postgres-heavy CPU patterns)
npx @insforge/cli diagnose db

Frequently paired with

• db-health — DB is the most common bottleneck behind CPU/memory pressure
• logs — correlate metric spikes to log events at the same timestamp
• advisor — --severity critical may already flag the underlying cause (e.g., missing index)

Policies

Active RLS (Row-Level Security) rules pulled from Postgres's pg_policies system view. The primary primitive for what RLS is currently allowing or denying — distinct from "what config we meant to deploy" (that lives in metadata / migration history).

Command

npx @insforge/cli db policies

Returns every policy: table, schema, policy name, command (SELECT / INSERT / UPDATE / DELETE / ALL), target role, USING expression, WITH CHECK expression.

Only specific InsForge-managed tables allow developer RLS changes. Check the relevant module skill or CLI reference before writing policy SQL for a managed table. If that table is listed as allowing RLS changes, normal RLS operations are allowed and should go in migrations.

Policy anatomy

How to read

For "why was this request denied?":

1. Identify the table from the request URL (/api/database/records/<table>). 2. List policies for that table — note cmd and roles. 3. Walk the USING / WITH CHECK expressions against the actual request:

• No policy for that role+cmd combo → denied by default. Need to add a policy.
• `USING` evaluates false for this row → row is invisible / not modifiable. Confirm the helper (e.g., auth.uid() returns the expected user_id).
• `WITH CHECK` evaluates false on insert → the new row's columns violate the policy. The insert payload is wrong, or the policy is too strict.

Common RLS bug shapes

Boundaries

• Lists active policies, doesn't simulate. Doesn't tell you "this specific request would be allowed" — combine with logs (postgREST.logs) to see the actual denial event.
• Doesn't include the helper function bodies. auth.uid() / requesting_user_id() are SQL functions; inspect via db query if you need to verify they return what you expect.
• Only listed managed tables allow RLS changes. Check the relevant module skill or CLI reference before changing RLS on a managed table. If the table is listed, put normal RLS operations in migrations; keep normal schema changes in public.

Example

User reports: "logged-in user gets 403 trying to GET /api/database/records/posts".

# 1. See the denial event
npx @insforge/cli logs postgREST.logs --limit 50

# 2. List policies on the posts table
npx @insforge/cli db policies

# 3. If the project uses third-party auth, verify the helper
npx @insforge/cli db query "SELECT requesting_user_id()"

# 4. Confirm the user's JWT contains the expected claim (auth config in metadata)
npx @insforge/cli metadata --json

Frequently paired with

• logs — postgREST.logs shows the actual RLS denial events; pair with policies to identify which rule fired
• metadata — auth config determines which claim feeds auth.uid() / requesting_user_id()
• advisor — security category often flags missing/overly-permissive RLS policies