render-oss/render-debug

Debug Render Deployments

Analyze deployment failures using logs, metrics, and database queries. Identify root causes and apply fixes.

When to Use This Skill

Activate this skill when:

• Deployment fails on Render
• Service won't start or keeps crashing
• User mentions errors, logs, or debugging
• Health checks are timing out
• Application errors in production
• Performance issues (slow responses)
• Database connection problems

Prerequisites

MCP tools (preferred): Test with list_services() - provides structured data

CLI (fallback): render --version - use if MCP tools unavailable

Authentication: For MCP, use an API key (set in the MCP config or via the RENDER_API_KEY env var, depending on tool). For CLI, verify with render whoami -o json.

Workspace: get_selected_workspace() or render workspace current -o json

Note: MCP tools require the Render MCP server. If unavailable, use the CLI for logs and deploy status; metrics and structured database queries require MCP.

MCP Setup

If list_services() fails, set up the Render MCP server. For detailed per-tool walkthroughs, see render-mcp.

Quick setup: Add the Render MCP server to your AI tool's MCP config:

• URL: https://mcp.render.com/mcp
• Auth header: Authorization: Bearer <YOUR_API_KEY>
• API key: https://dashboard.render.com/u/*/settings#api-keys

After configuring, restart your tool and retry list_services(). Then set your workspace with list_workspaces() / get_selected_workspace().

---

Debugging Workflow

Step 1: Identify Failed Service

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>")

Step 2: Retrieve Logs

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)

Step 3: Analyze Error Patterns

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.

Step 4: Check Metrics (Performance Issues)

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

Step 5: Debug Database Issues

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

Step 6: Apply Fix

For environment variables:

update_environment_variables(
  serviceId: "<service-id>",
  envVars: [{"key": "MISSING_VAR", "value": "value"}]
)

For code changes:

1. Edit the source file
2. Commit and push
3. Deploy triggers automatically (if auto-deploy enabled)

Step 7: Verify Fix

# 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"])

---

Quick Workflows

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

---

Quick Reference

MCP Tools

# 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}])

CLI Commands (Fallback)

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

---

References

• Error patterns: references/error-patterns.md
• Metrics debugging: references/metrics-debugging.md
• Database debugging: references/database-debugging.md
• Quick workflows: references/quick-workflows.md
• Log analysis: references/log-analysis.md
• Troubleshooting: references/troubleshooting.md

Related Skills

• render-deploy — Deploy new applications to Render
• render-monitor — Ongoing service health monitoring
• render-mcp — MCP server setup and tool catalog