--- id: daily-insforge-debug name: "insforge-debug" url: https://skills.yangsir.net/skill/daily-insforge-debug author: insforge domain: ai-system-observability-sre tags: ["debugging", "diagnostics", "devops", "troubleshooting", "log-analysis"] install_count: 6100 rating: 4.40 (20 reviews) github: https://github.com/insforge/agent-skills --- # insforge-debug > 诊断InsForge项目问题，从前端SDK错误到后端基础设施故障，运行命令定位问题并输出日志 **Stats**: 6,100 installs · 4.4/5 (20 reviews) ## Before / After 对比 ### 项目故障诊断 **Before**: 手动检查各个服务状态，分散查看日志文件和错误信息，猜测可能的问题点反复测试，一个故障排查需要1-2小时 **After**: 一键运行诊断命令收集所有日志和状态，自动关联错误和事件，5分钟定位故障根因并生成详细诊断报告 | Metric | Before | After | Change | |---|---|---|---| | 故障定位时间 | 90分钟 | 5分钟 | -94% | ## Readme # insforge-debug # 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. Symptom Scenario SDK returns `{ data: null, error: {...} }` [#1 SDK Error](#scenario-1-sdk-returns-error-object) HTTP 400 / 401 / 403 / 404 / 429 / 500 [#2 HTTP Status Code](#scenario-2-http-status-code-anomaly) Function throws or times out [#3 Edge Function Failure](#scenario-3-edge-function-execution-failuretimeout) Query slow or hangs [#4 Database Slow](#scenario-4-database-query-slow-or-unresponsive) Login fails / token expired / RLS denied [#5 Auth Failure](#scenario-5-authenticationauthorization-failure) Channel won't connect / messages missing [#6 Realtime Issues](#scenario-6-realtime-channel-issues) High CPU/memory, all responses slow [#7 Backend Performance](#scenario-7-backend-performance-degradation) `functions deploy` fails [#8 Function Deploy](#scenario-8-edge-function-deploy-failure) `deployments deploy` fails / Vercel error [#9 Frontend Deploy](#scenario-9-frontend-vercel-deploy-failure) ## Scenario 1: SDK Returns Error Object **Symptoms**: SDK call returns `{ data: null, error: { code, message, details } }`. PostgREST error codes like `PGRST301`, `PGRST204`, etc. **Steps**: - Read the error object — extract `code`, `message`, `details` from the SDK response. - Check aggregated error logs to find matching backend errors: ``` npx @insforge/cli diagnose logs ``` - Based on the error code prefix, drill into the relevant log source: Error pattern Log source Command `PGRST*` (PostgREST) postgREST.logs `npx @insforge/cli logs postgREST.logs --limit 50` Database/SQL errors postgres.logs `npx @insforge/cli logs postgres.logs --limit 50` Generic 500 / server error insforge.logs `npx @insforge/cli logs insforge.logs --limit 50` - If the error is DB-related, check database health for additional context: ``` 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**: - Identify the status code from the response. - Follow the path for that status code: Status What to check Command 400 Request payload/params malformed `npx @insforge/cli logs postgREST.logs --limit 50` 401 Auth token missing or expired `npx @insforge/cli logs insforge.logs --limit 50` 403 RLS policy or permission denied `npx @insforge/cli logs insforge.logs --limit 50` 404 Endpoint or resource doesn't exist `npx @insforge/cli metadata --json` 429 Rate limit hit — **no backend logs recorded** See 429 note below 500 Server-side error `npx @insforge/cli diagnose logs` - For 500 errors, also check aggregate error logs across all sources: ``` npx @insforge/cli diagnose logs ``` - **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: ``` 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**: - Check function execution logs: ``` npx @insforge/cli logs function.logs --limit 50 ``` - Verify the function exists and is active: ``` npx @insforge/cli functions list ``` - Inspect the function source for obvious issues: ``` npx @insforge/cli functions code ``` **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**: - Check database health — slow queries, active connections, locks: ``` npx @insforge/cli diagnose db --check slow-queries,connections,locks ``` - Check postgres logs for query errors or warnings: ``` npx @insforge/cli logs postgres.logs --limit 50 ``` - Check index usage and table bloat: ``` npx @insforge/cli diagnose db --check index-usage,bloat,cache-hit,size ``` - If the whole system feels slow, check EC2 instance metrics: ``` 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**: - Check insforge.logs for auth-related errors (login failures, token issues, OAuth errors): ``` npx @insforge/cli logs insforge.logs --limit 50 ``` - Check postgREST.logs for RLS policy violations: ``` npx @insforge/cli logs postgREST.logs --limit 50 ``` - Verify the project's auth configuration: ``` npx @insforge/cli metadata --json ``` - If RLS suspected, inspect current policies: ``` 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**: - Check insforge.logs for realtime/WebSocket errors: ``` npx @insforge/cli logs insforge.logs --limit 50 ``` - Verify the channel pattern exists and is enabled: ``` npx @insforge/cli db query "SELECT pattern, description, enabled FROM realtime.channels" ``` - If access is restricted, check RLS on realtime tables: ``` npx @insforge/cli db policies ``` - If the issue is widespread (all channels affected), check overall backend health: ``` 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**: - Check EC2 instance metrics — CPU, memory, disk, network: ``` npx @insforge/cli diagnose metrics --range 1h ``` - Check database health (often the bottleneck): ``` npx @insforge/cli diagnose db ``` - Check aggregate error logs: ``` npx @insforge/cli diagnose logs ``` - Check advisor for known critical issues: ``` 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 ` command fails, function not appearing in the list after deploy. **Steps**: - Re-run the deploy command and capture the error output: ``` npx @insforge/cli functions deploy ``` - Check deployment-related errors: ``` npx @insforge/cli logs function-deploy.logs --limit 50 ``` - Verify whether the function exists in the list: ``` 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**: - Check recent deployment attempts: ``` npx @insforge/cli deployments list ``` - Get the status and error details for the failed deployment: ``` npx @insforge/cli deployments status --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. - Verify the local build succeeds before investigating further: ``` 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 ``` npx @insforge/cli logs [--limit ] ``` Source Description `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 ``` # 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 ] # Advisor scan results npx @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] [--limit ] # Database health checks npx @insforge/cli diagnose db [--check ] # 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 ] [--limit ] ``` ### Supporting Commands ``` # 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 # Secrets npx @insforge/cli secrets list [--all] npx @insforge/cli secrets get npx @insforge/cli secrets add [--reserved] [--expires ] # Database npx @insforge/cli db policies npx @insforge/cli db query "" # Deployments npx @insforge/cli deployments list npx @insforge/cli deployments status --json ``` Weekly Installs583Repository[insforge/agent-skills](https://github.com/insforge/agent-skills)GitHub Stars12First Seen6 days agoSecurity Audits[Gen Agent Trust HubPass](/insforge/agent-skills/insforge-debug/security/agent-trust-hub)[SocketWarn](/insforge/agent-skills/insforge-debug/security/socket)[SnykFail](/insforge/agent-skills/insforge-debug/security/snyk)Installed ongemini-cli583antigravity583cline583github-copilot583cursor583codex583 --- *Source: https://skills.yangsir.net/skill/daily-insforge-debug* *Markdown mirror: https://skills.yangsir.net/api/skill/daily-insforge-debug/markdown*