Terminal
Terminal/Skill
Diagnoses failed Render deploys from build and runtime logs, metrics, and database state, and suggests fixes for common errors.
By Render
Works with
npx skills add render-oss/skills --skill render-debugAnalyze deployment failures using logs, metrics, and database queries. Identify root causes and apply fixes.
Activate this skill when:
Before reading logs, metrics, or database state, follow references/render-access.md to establish access and verify the intended workspace. Prefer MCP when available; the CLI can provide logs and deploy status, while metrics and structured database queries require MCP.
When the failure involves configuration or secrets, read references/environment-variables.md before inspecting or changing service variables.
When the failure involves deploy state, rollout, health checks, restart, rollback, or shutdown, read references/deployments.md before diagnosing it.
list_services()
If MCP isn't configured, ask whether to set it up (preferred) or continue with CLI. Then proceed.
Look for services with failed status. Get details:
get_service(serviceId: "<id>")
Build/Deploy Logs (most failures):
list_logs(resource: ["<service-id>"], type: ["build"], limit: 200)
Runtime Error Logs:
list_logs(resource: ["<service-id>"], level: ["error"], limit: 100)
Search for Specific Errors:
list_logs(resource: ["<service-id>"], text: ["KeyError", "ECONNREFUSED"], limit: 50)
HTTP Error Logs:
list_logs(resource: ["<service-id>"], statusCode: ["500", "502", "503"], limit: 50)
Match log errors against known patterns:
| Error | Log Pattern | Common Fix |
|---|---|---|
| MISSING_ENV_VAR | KeyError, not defined | Add to render.yaml or update_environment_variables |
| PORT_BINDING | EADDRINUSE | Use 0.0.0.0:$PORT |
| MISSING_DEPENDENCY | Cannot find module | Add to package.json/requirements.txt |
| DATABASE_CONNECTION | ECONNREFUSED :5432 | Check DATABASE_URL, DB status |
| HEALTH_CHECK | Health check timeout | Add /health endpoint, check port binding |
| OUT_OF_MEMORY | heap out of memory, exit 137 | Optimize memory or upgrade plan |
| BUILD_FAILURE | Command failed | Fix build command or dependencies |
Full error catalog: references/error-patterns.md
If errors repeat across deploys: Switch from incremental fixes to a broader sweep. Scan the codebase/config for all likely causes in that error class (related env vars, build config, dependencies, or type errors) and address them together before the next redeploy.
For crashes, slow responses, or resource issues:
get_metrics(
resourceId: "<service-id>",
metricTypes: ["cpu_usage", "memory_usage", "memory_limit"]
)
get_metrics(
resourceId: "<service-id>",
metricTypes: ["http_latency"],
httpLatencyQuantile: 0.95
)
Detailed metrics guide: references/metrics-debugging.md
For database-related errors:
# Check database status
list_postgres_instances()
# Check connections
get_metrics(resourceId: "<postgres-id>", metricTypes: ["active_connections"])
# Query directly
query_render_postgres(
postgresId: "<postgres-id>",
sql: "SELECT state, count(*) FROM pg_stat_activity GROUP BY state"
)
Detailed database guide: references/database-debugging.md
For environment variables:
update_environment_variables(
serviceId: "<service-id>",
envVars: [{"key": "MISSING_VAR", "value": "value"}]
)
For code changes:
# Check deploy status
list_deploys(serviceId: "<service-id>", limit: 1)
# Check for new errors
list_logs(resource: ["<service-id>"], level: ["error"], limit: 20)
# Check metrics
get_metrics(resourceId: "<service-id>", metricTypes: ["http_request_count"])
Pre-built debugging sequences for common scenarios:
| Scenario | Workflow |
|---|---|
| Deploy failed | list_deploys → list_logs(type: build) → fix → redeploy |
| App crashing | list_logs(level: error) → get_metrics(memory) → fix |
| App slow | get_metrics(http_latency) → get_metrics(cpu) → query_postgres |
| DB connection | list_postgres → get_metrics(connections) → query_postgres |
| Post-deploy check | list_deploys → list_logs(error) → get_metrics |
Detailed workflows: references/quick-workflows.md
# Service Discovery
list_services()
get_service(serviceId: "<id>")
list_postgres_instances()
# Logs
list_logs(resource: ["<id>"], level: ["error"], limit: 100)
list_logs(resource: ["<id>"], type: ["build"], limit: 200)
list_logs(resource: ["<id>"], text: ["search"], limit: 50)
# Metrics
get_metrics(resourceId: "<id>", metricTypes: ["cpu_usage", "memory_usage"])
get_metrics(resourceId: "<id>", metricTypes: ["http_latency"], httpLatencyQuantile: 0.95)
# Database
query_render_postgres(postgresId: "<id>", sql: "SELECT ...")
# Deployments
list_deploys(serviceId: "<id>", limit: 5)
# Environment Variables
update_environment_variables(serviceId: "<id>", envVars: [{key, value}])
render services -o json
render logs -r <service-id> --level error -o json
render logs -r <service-id> --tail -o text
render deploys create <service-id> --wait
Whenever this skill directs you to consult current Render documentation:
curl. Do not substitute web-search summaries for the document.When a task requires multiple references, apply this workflow to each one and distinguish the documents you verified from those that remain unavailable.