Render Debug

RenderOfficialCreated by Render

Skill
Tool integration
Cloud and DevOps
MIT
Low risk

From the author

Debug failed Render deployments by analyzing logs, metrics, and database state. Identifies errors (missing env vars, port binding, OOM, etc.) and suggests fixes. Use when deployments fail, services won't start, or users mention errors, logs, or debugging.

— the description by Render

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The render-debug skill provides a structured approach to troubleshooting Render services. It guides users through identifying failed services, retrieving relevant logs, analyzing performance metrics, and querying database state to pinpoint root causes like configuration errors, resource exhaustion, or connection issues. The skill integrates with Render's MCP tools to automate data collection and suggests common fixes for identified error patterns.

What it does

Lists and inspects status of Render services and deployments
Retrieves and filters build, runtime, and HTTP error logs
Analyzes CPU, memory, and latency metrics to identify performance bottlenecks
Queries PostgreSQL instances to diagnose connection and query performance issues
Maps common error patterns to actionable remediation steps
Provides workflows for verifying fixes through log and metric validation

When to use it

When a Render deployment fails to complete
When a service crashes or fails to start
When application health checks are timing out
When users report production errors or performance degradation
When diagnosing database connection or query latency problems

Advantages

Standardizes the debugging process for Render environments
Reduces manual log searching by targeting specific error types
Provides direct access to database diagnostics via SQL queries
Offers clear remediation paths for common configuration and resource issues

Usage examples

“My service is failing to deploy on Render, can you help?”: The agent will list your services, identify the failed one, retrieve the relevant build logs, and analyze them against known error patterns to suggest a fix.
“My app is running very slowly, check the metrics.”: The agent will fetch CPU, memory, and HTTP latency metrics for the service to determine if resource constraints or slow database queries are the cause.
“I am getting ECONNREFUSED errors from my database.”: The agent will check the database status, analyze active connection counts, and query pg_stat_activity to identify potential connection pool exhaustion.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/render-oss/render-debug/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip render-debug.zip -d .agents/skills

Documentation by Render

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

Render Access

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.

Debugging Workflow

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.

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:

Edit the source file
Commit and push
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

Render access: references/render-access.md
Environment variables: references/environment-variables.md
Compute plans: references/compute-plans.md
Deployments: references/deployments.md
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

render-deploy — Deploy new applications to Render
render-monitor — Ongoing service health monitoring
render-mcp — MCP server setup and capability discovery

Current documentation retrieval

Whenever this skill directs you to consult current Render documentation:

Retrieve the linked Markdown document directly with an available URL-fetching tool or HTTP client, such as curl. Do not substitute web-search summaries for the document.
Confirm that retrieval succeeded and returned the expected document, then read its contents. Saving a file or printing its path is not sufficient.
If the request fails or your tool cannot read the Markdown response, open and read the linked HTML version instead.
If neither version can be retrieved, disclose that the current reference is unavailable and follow any topic-specific fallback in the skill. Use bundled guidance only for stable constraints, and do not guess at changeable platform details.

When a task requires multiple references, apply this workflow to each one and distinguish the documents you verified from those that remain unavailable.

Files

ATTRIBUTION.mdAdded by AutoGineer878 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md8.3 KiB
references/compute-plans.md2.3 KiB
references/database-debugging.md8.8 KiB
references/deployments.md7.9 KiB
references/environment-variables.md4.5 KiB
references/error-patterns.md18.7 KiB
references/log-analysis.md9.9 KiB
references/metrics-debugging.md6.4 KiB
references/quick-workflows.md6.2 KiB
references/render-access.md4.7 KiB
references/troubleshooting.md12.3 KiB

references/log-analysis.md

Render Log Analysis Guide

How to read, interpret, and analyze Render logs to identify deployment and runtime issues.

Understanding Render Logs

Log Types

Render provides different log types for different purposes:

Deploy Logs - Build and deployment process
Runtime Logs - Application output after deployment
System Logs - Render platform events

Log Levels

Logs are categorized by severity:

error - Critical errors requiring attention
warn - Warning messages (potential issues)
info - Informational messages
debug - Detailed debugging information

CLI Commands for Logs

Basic Log Retrieval

Get deploy logs (build/deployment phase):

render logs -r <service-id> --type deploy -o json

Get runtime logs (after service starts):

render logs -r <service-id> -o json

Get error logs only:

render logs -r <service-id> --level error -o json

Get recent logs (limit output):

render logs -r <service-id> --limit 200 -o json

Stream logs in real-time:

render logs -r <service-id> --tail -o text

Advanced Filtering

Combine filters:

render logs -r <service-id> --type deploy --level error --limit 100 -o json

Output formats:

-o json - JSON format (easier to parse)
-o text - Plain text (human-readable)
-o yaml - YAML format

Reading Deploy Logs

Deploy logs show the build and deployment process. Read them sequentially from top to bottom.

Typical Deploy Log Structure

1. Repository cloning
   → Cloning repository from git remote

2. Environment setup
   → Setting up build environment
   → Installing runtime (node, python, etc.)

3. Build phase
   → Running buildCommand
   → Installing dependencies
   → Compiling code

4. Pre-deploy checks
   → Validating configuration
   → Checking for required files

5. Deploy phase
   → Running startCommand
   → Starting service

6. Health checks
   → Waiting for service to respond
   → Verifying health check endpoint

7. Success or failure
   → Deploy succeeded
   → OR: Deploy failed with error

Key Sections to Check

1. Build Command Execution:

==> Running 'npm ci'
npm WARN deprecated [email protected]
added 250 packages in 15s

Look for:

npm ERR! - npm errors
error: - compilation errors
FATAL: - critical build errors

2. Start Command Execution:

==> Running 'npm start'
> [email protected] start
> node server.js

Server listening on port 10000

Look for:

Server startup messages
Port binding confirmation
Error messages during startup

3. Health Check Results:

==> Checking service health at https://myapp.onrender.com/
Health check passed
Deploy succeeded

Look for:

Health check timeout - Service not responding
Health check failed - Service responding with error
Health check passed - Success

Reading Runtime Logs

Runtime logs show application output after successful deployment.

Understanding Runtime Log Entries

Each log entry typically contains:

{
  "timestamp": "2024-01-24T10:30:45.123Z",
  "level": "error",
  "message": "Database connection failed",
  "service": "web-app",
  "instance": "srv-abc123-instance-1"
}

Common Runtime Log Patterns

1. Application Startup:

Server started successfully
Listening on port 10000
Database connected

2. Request Handling:

GET /api/users 200 - 45ms
POST /api/auth 401 - 12ms

3. Errors:

Error: Cannot find module 'express'
UnhandledPromiseRejectionWarning: Error: Connection timeout
TypeError: Cannot read property 'id' of undefined

4. Database Operations:

Connected to PostgreSQL
Query executed: SELECT * FROM users
Database connection pool: 5/20 active

Identifying Error Location

Finding the Error Line

Look for these keywords:

Error:
Exception:
FATAL:
failed
crashed
timeout
refused

Error message structure:

Error: Cannot find module 'express'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:880:15)
    at Function.Module._load (internal/modules/cjs/loader.js:725:27)
    at Module.require (internal/modules/cjs/loader.js:952:19)
    at require (internal/modules/cjs/helpers.js:88:18)
    at Object.<anonymous> (/app/server.js:1:17)  ← YOUR CODE

The first line with /app/ is usually your code.

Stack Trace Analysis

Reading stack traces:

Error message - Top line describes the error
Stack frames - Lines below show call path
File locations - Look for paths starting with /app/
Line numbers - Shows exact line in your code

Example:

ReferenceError: DATABASE_URL is not defined
    at connectDatabase (/app/database.js:15:23)  ← Error on line 15
    at startup (/app/server.js:10:5)             ← Called from line 10
    at Object.<anonymous> (/app/server.js:50:1)  ← App entry point

Action: Open /app/database.js line 15 to see the issue.

Common Log Patterns by Error Type

Missing Environment Variable

Error: DATABASE_URL is not defined
    at /app/config.js:12:45

ReferenceError: process.env.API_KEY is undefined

KeyError: 'JWT_SECRET'

Action: Add to render.yaml envVars

Port Binding Error

Error: listen EADDRINUSE: address already in use 0.0.0.0:3000
    at Server.setupListenHandle [as _listen2] (net.js:1313:16)

Address already in use (os error 48)

Action: Update code to use process.env.PORT

Database Connection Error

Error: connect ECONNREFUSED 127.0.0.1:5432
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1145:16)

could not connect to server: Connection refused
	Is the server running on host "127.0.0.1" and accepting
	TCP/IP connections on port 5432?

Action: Verify DATABASE_URL and database status

Health Check Timeout

==> Checking service health at https://myapp.onrender.com/
Health check timeout after 300 seconds
Deploy failed

Action: Check port binding and add /health endpoint

Out of Memory

<--- Last few GCs --->

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

Action: Optimize memory usage or upgrade plan

Filtering Relevant Logs

What to Focus On

For Build Failures:

Look at build command output
Find first error in build logs
Check dependency installation section
Review compilation errors

For Runtime Failures:

Look at start command output
Check first few seconds of runtime logs
Look for startup errors
Check health check section

What to Ignore (Usually)

Deprecation warnings (unless they cause errors)
Info-level messages
Successful operation logs
Normal request logs (200 responses)

Tips for Efficient Log Analysis

1. Start with Error-Level Logs

render logs -r <service-id> --level error -o json

This filters out noise and shows only critical issues.

2. Use JSON Output for Parsing

JSON format is easier to search and parse programmatically:

render logs -r <service-id> -o json | grep "DATABASE_URL"

3. Limit Output

Don't retrieve all logs at once:

render logs -r <service-id> --limit 200 -o json

Most errors appear in recent logs.

4. Focus on Deployment Logs First

If deployment failed, deploy logs contain the error:

render logs -r <service-id> --type deploy --level error -o json

5. Use Real-Time Streaming

Watch logs as deployment happens:

render logs -r <service-id> --tail -o text

6. Search for Specific Patterns

Look for common error keywords:

"Error:"
"Exception"
"failed"
"timeout"
"refused"
"undefined"
"not found"

Troubleshooting Workflow

Step 1: Get error-level logs

render logs -r <service-id> --level error -o json --limit 100

Step 2: Identify error type

Missing env var?
Port binding issue?
Build failure?
Database connection?

Step 3: Get context

render logs -r <service-id> --limit 500 -o json

Read logs around the error for context.

Step 4: Match to error pattern Refer to error-patterns.md for known patterns.

Step 5: Apply fix Refer to troubleshooting.md for fix procedures.

Log Examples

Example 1: Successful Deployment

==> Cloning from https://github.com/user/repo...
==> Running build command 'npm ci'
added 250 packages in 15s
==> Running start command 'npm start'
Server listening on port 10000
==> Health check passed
Deploy succeeded

Example 2: Missing Environment Variable

==> Running start command 'npm start'
Server starting...
ReferenceError: DATABASE_URL is not defined
    at connectDatabase (/app/database.js:15:23)
Process exited with code 1
Deploy failed

Example 3: Port Binding Error

==> Running start command 'npm start'
Server starting on port 3000...
Error: listen EADDRINUSE: address already in use 0.0.0.0:3000
Process exited with code 1
Deploy failed

Example 4: Health Check Timeout

==> Running start command 'npm start'
Server started
==> Checking service health at https://myapp.onrender.com/
Health check timeout after 300 seconds
Deploy failed

Quick Reference

Log Commands Cheat Sheet

# Error logs only
render logs -r <id> --level error -o json

# Deploy logs
render logs -r <id> --type deploy -o json

# Stream logs
render logs -r <id> --tail -o text

# Recent logs
render logs -r <id> --limit 200 -o json

# All options combined
render logs -r <id> --type deploy --level error --limit 100 -o json

Error Keywords to Search For

Error:
Exception
FATAL
failed
timeout
refused
undefined
not found
cannot
invalid

Next Steps

After analyzing logs:

Identify error pattern in error-patterns.md
Follow fix procedure in troubleshooting.md
Apply fix and redeploy
Monitor logs during next deployment

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server

The author says: Requires Render MCP tools or CLI

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Render

Publisher

Render (Official)

Source

render-oss/skills · skills/render-debug · commit b985a63

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Render or Render.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download render-debug.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Render

Debug Render Deployments

When to Use This Skill

Render Access

Debugging Workflow

Step 1: Identify Failed Service

Step 2: Retrieve Logs

Step 3: Analyze Error Patterns

Step 4: Check Metrics (Performance Issues)

Step 5: Debug Database Issues

Step 6: Apply Fix

Step 7: Verify Fix

Quick Workflows

Quick Reference

MCP Tools

CLI Commands (Fallback)

References

Related Skills

Current documentation retrieval

Files

references/log-analysis.md

Render Log Analysis Guide

Understanding Render Logs

Log Types

Log Levels

CLI Commands for Logs

Basic Log Retrieval

Advanced Filtering

Reading Deploy Logs

Typical Deploy Log Structure

Key Sections to Check

Reading Runtime Logs

Understanding Runtime Log Entries

Common Runtime Log Patterns

Identifying Error Location

Finding the Error Line

Stack Trace Analysis

Common Log Patterns by Error Type

Missing Environment Variable

Port Binding Error

Database Connection Error

Health Check Timeout

Out of Memory

Filtering Relevant Logs

What to Focus On

What to Ignore (Usually)

Tips for Efficient Log Analysis

1. Start with Error-Level Logs

2. Use JSON Output for Parsing

3. Limit Output

4. Focus on Deployment Logs First

5. Use Real-Time Streaming

6. Search for Specific Patterns

Troubleshooting Workflow

Log Examples

Example 1: Successful Deployment

Example 2: Missing Environment Variable

Example 3: Port Binding Error

Example 4: Health Check Timeout

Quick Reference

Log Commands Cheat Sheet

Error Keywords to Search For

Next Steps

Requirements and compatibility

Security

Attribution and licence

Related skills

Observability And Instrumentation

Spark Memory Thermal Ops

Gke Alert Configuration

Application Performance Observability Engineer

Distributed Debugging Devops Troubleshooter

Distributed Tracing