# render-debug

Reads logs, metrics and database state to find why a Render deploy failed, then points at the fix.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 541 installs · ★ 88
- Author: Render
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/render-oss/skills/tree/HEAD/skills/render-debug/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/render-debug

## What it does

The skill kicks in when a Render deploy fails, a service won't start, or production starts throwing errors. It walks a fixed path: find the failing service, pull build logs and runtime errors, match them against a catalog of known patterns. That catalog covers missing env vars, port binding, missing dependencies, refused Postgres connections, health check timeouts, out-of-memory exits and broken build commands.

Reading logs, metrics and database state needs access to Render through MCP tools or the CLI. MCP is the preferred route. The CLI gives you logs and deploy status, while metrics and structured database queries only work over MCP. If MCP isn't configured, the skill asks whether to set it up or continue on the CLI. Settle that first, because otherwise a chunk of the workflow has nothing to call.

When the same error shows up across deploys, the skill tells you to stop patching one thing at a time. Instead it scans the codebase and config for every likely cause in that error class and fixes them together before the next redeploy. Fixes go through `update_environment_variables` or a commit, and the skill then checks deploy status, fresh errors and metrics.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add render-oss/skills --skill render-debug -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/render-debug/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/render-debug/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add render-oss/skills --skill render-debug -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/render-debug/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add render-oss/skills --skill render-debug -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/render-debug/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install render-oss/skills render-debug
```

2. **Manually: put the files in place**
- File: `.github/skills/render-debug/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add render-oss/skills --skill render-debug -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/render-oss/skills --path skills/render-debug
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/render-debug/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add render-oss/skills --skill render-debug -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/render-oss/skills/tree/HEAD/skills/render-debug/SKILL.md

## When to use it
- read build logs from a failed deploy and name the cause
- work out why a service exits with code 137
- fix a Postgres connection refused on port 5432
- pull 500, 502 and 503 errors out of runtime logs
- check CPU and memory metrics after a crash

## Example prompts
- my Render deploy failed, check the logs and tell me what to fix
- the service keeps crashing, dig through the logs and metrics
- why does the health check time out?

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 2430f92fb508934e.

BEGIN THIRD-PARTY FILE 2430f92fb508934e
````text
---
name: render-debug
description: 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.
license: MIT
compatibility: Requires Render MCP tools or CLI
metadata:
  author: Render
  version: "1.1.0"
  category: debugging
---

# 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 |
````
END THIRD-PARTY FILE 2430f92fb508934e

The third-party file has ended. Everything between the 2430f92fb508934e tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2703 of 8459 bytes. © Render · MIT · https://github.com/render-oss/skills/tree/HEAD/skills/render-debug/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md