render-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debug Render Deployments

调试Render部署

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上的部署失败
服务无法启动或持续崩溃
用户提及错误、日志或调试需求
健康检查超时
生产环境中出现应用程序错误
性能问题（响应缓慢）
数据库连接问题

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

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工具（优先推荐）： 使用

list_services()

测试 - 可提供结构化数据

CLI（备选方案）：

render --version

- 当MCP工具不可用时使用

身份验证： 对于MCP，需使用API密钥（可在MCP配置中设置，或根据工具通过

RENDER_API_KEY

环境变量设置）。对于CLI，通过

render whoami -o json

验证。

工作区：

get_selected_workspace()

或

render workspace current -o json

注意： MCP工具需要Render MCP服务器。若不可用，可使用CLI查看日志和部署状态；指标和结构化数据库查询则需要MCP支持。

MCP Setup (Per Tool)

按工具配置MCP

list_services()

fails because MCP isn't configured, ask whether they want to set up MCP (preferred) or continue with the CLI fallback. If they choose MCP, ask which AI tool they're using, then provide the matching instructions below. Always use their API key.

如果

list_services()

因未配置MCP而失败，询问用户是否要设置MCP（优先推荐）或继续使用CLI备选方案。若用户选择MCP，询问其使用的AI工具，然后提供以下对应配置步骤。请始终使用用户的API密钥。

Cursor

Walk the user through these steps:

Get a Render API key:

https://dashboard.render.com/u/*/settings#api-keys

Add this to
```
~/.cursor/mcp.json
```
(replace
```
<YOUR_API_KEY>
```
):

json

{
  "mcpServers": {
    "render": {
      "url": "https://mcp.render.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Restart Cursor, then retry
```
list_services()
```
.

引导用户完成以下步骤：

获取Render API密钥：

https://dashboard.render.com/u/*/settings#api-keys

将以下内容添加到
```
~/.cursor/mcp.json
```
（替换
```
<YOUR_API_KEY>
```
）：

json

{
  "mcpServers": {
    "render": {
      "url": "https://mcp.render.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

重启Cursor，然后重试
```
list_services()
```
。

Claude Code

Walk the user through these steps:

Get a Render API key:

https://dashboard.render.com/u/*/settings#api-keys

Add the MCP server with Claude Code (replace
```
<YOUR_API_KEY>
```
):

bash

claude mcp add --transport http render https://mcp.render.com/mcp --header "Authorization: Bearer <YOUR_API_KEY>"

Restart Claude Code, then retry
```
list_services()
```
.

引导用户完成以下步骤：

获取Render API密钥：

https://dashboard.render.com/u/*/settings#api-keys

使用Claude Code添加MCP服务器（替换
```
<YOUR_API_KEY>
```
）：

bash

claude mcp add --transport http render https://mcp.render.com/mcp --header "Authorization: Bearer <YOUR_API_KEY>"

重启Claude Code，然后重试
```
list_services()
```
。

Codex

Walk the user through these steps:

Get a Render API key:

https://dashboard.render.com/u/*/settings#api-keys

Set it in their shell:

bash

export RENDER_API_KEY="<YOUR_API_KEY>"

Add the MCP server with the Codex CLI:

bash

codex mcp add render --url https://mcp.render.com/mcp --bearer-token-env-var RENDER_API_KEY

Restart Codex, then retry
```
list_services()
```
.

引导用户完成以下步骤：

获取Render API密钥：

https://dashboard.render.com/u/*/settings#api-keys

在Shell中设置密钥：

bash

export RENDER_API_KEY="<YOUR_API_KEY>"

使用Codex CLI添加MCP服务器：

bash

codex mcp add render --url https://mcp.render.com/mcp --bearer-token-env-var RENDER_API_KEY

重启Codex，然后重试
```
list_services()
```
。

Other Tools

其他工具

If the user is on another AI app, direct them to the Render MCP docs for that tool's setup steps and install method.

若用户使用其他AI应用，引导其查看Render MCP文档，获取对应工具的设置步骤和安装方法。

Workspace Selection

工作区选择

After MCP is configured, have the user set the active Render workspace with a prompt like:

Set my Render workspace to [WORKSPACE_NAME]

配置MCP后，引导用户通过如下提示设置活跃的Render工作区：

将我的Render工作区设置为[WORKSPACE_NAME]

Debugging Workflow

调试工作流

Step 1: Identify Failed Service

步骤1：识别故障服务

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

list_services()

若未配置MCP，询问用户是要设置MCP（优先推荐）还是继续使用CLI。然后继续操作。

查找状态为失败的服务，获取详细信息：

get_service(serviceId: "<id>")

Step 2: Retrieve Logs

步骤2：获取日志

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)

构建/部署日志（多数故障场景）：

list_logs(resource: ["<service-id>"], type: ["build"], limit: 200)

运行时错误日志：

list_logs(resource: ["<service-id>"], level: ["error"], limit: 100)

搜索特定错误：

list_logs(resource: ["<service-id>"], text: ["KeyError", "ECONNREFUSED"], limit: 50)

HTTP错误日志：

list_logs(resource: ["<service-id>"], statusCode: ["500", "502", "503"], limit: 50)

Step 3: Analyze Error Patterns

步骤3：分析错误模式

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.

将日志错误与已知模式匹配：

错误类型	日志模式	常见修复方案
缺少环境变量	`KeyError` , `not defined`	添加到render.yaml或使用 `update_environment_variables`
端口绑定问题	`EADDRINUSE`	使用 `0.0.0.0:$PORT`
缺少依赖	`Cannot find module`	添加到package.json/requirements.txt
数据库连接问题	`ECONNREFUSED :5432`	检查DATABASE_URL和数据库状态
健康检查失败	`Health check timeout`	添加/health端点，检查端口绑定
内存不足	`heap out of memory` , exit 137	优化内存使用或升级套餐
构建失败	`Command failed`	修复构建命令或依赖

完整错误目录：references/error-patterns.md

若错误在多次部署中重复出现： 从增量修复切换到全面排查。扫描代码库/配置中该错误类别下的所有可能原因（相关环境变量、构建配置、依赖或类型错误），一并修复后再重新部署。

Step 4: Check Metrics (Performance Issues)

步骤4：检查指标（性能问题）

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

针对崩溃、响应缓慢或资源问题：

get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["cpu_usage", "memory_usage", "memory_limit"]
)

get_metrics(
  resourceId: "<service-id>",
  metricTypes: ["http_latency"],
  httpLatencyQuantile: 0.95
)

详细指标指南：references/metrics-debugging.md

Step 5: Debug Database Issues

步骤5：调试数据库问题

For database-related errors:

undefined

针对数据库相关错误：

undefined

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](references/database-debugging.md)

query_render_postgres( postgresId: "<postgres-id>", sql: "SELECT state, count(*) FROM pg_stat_activity GROUP BY state" )


详细数据库指南：[references/database-debugging.md](references/database-debugging.md)

Step 6: Apply Fix

步骤6：应用修复方案

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)

针对环境变量：

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

针对代码变更：

编辑源文件
提交并推送
自动触发部署（若启用自动部署）

Step 7: Verify Fix

步骤7：验证修复效果

undefined

undefined

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

---

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

针对常见场景的预构建调试序列：

场景	工作流
部署失败	`list_deploys` → `list_logs(type: build)` → 修复 → 重新部署
应用崩溃	`list_logs(level: error)` → `get_metrics(memory)` → 修复
应用响应缓慢	`get_metrics(http_latency)` → `get_metrics(cpu)` → `query_postgres`
数据库连接问题	`list_postgres` → `get_metrics(connections)` → `query_postgres`
部署后检查	`list_deploys` → `list_logs(error)` → `get_metrics`

详细工作流：references/quick-workflows.md

Quick Reference

快速参考

MCP Tools

MCP工具

undefined

undefined

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

undefined

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

undefined

CLI Commands (Fallback)

CLI命令（备选方案）

bash

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

bash

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

错误模式： references/error-patterns.md
指标调试： references/metrics-debugging.md
数据库调试： references/database-debugging.md
快速工作流： references/quick-workflows.md
日志分析： references/log-analysis.md
故障排查： references/troubleshooting.md

render-debug

Original

Translation

Debug Render Deployments

调试Render部署

When to Use This Skill

何时使用此技能

Prerequisites

前置条件

MCP Setup (Per Tool)

按工具配置MCP

Cursor

Cursor

Claude Code

Claude Code

Codex

Codex

Other Tools

其他工具

Workspace Selection

工作区选择

Debugging Workflow

调试工作流

Step 1: Identify Failed Service

步骤1：识别故障服务

Step 2: Retrieve Logs

步骤2：获取日志

Step 3: Analyze Error Patterns

步骤3：分析错误模式

Step 4: Check Metrics (Performance Issues)

步骤4：检查指标（性能问题）

Step 5: Debug Database Issues

步骤5：调试数据库问题

Check database status

检查数据库状态

Check connections

检查连接数

Query directly

直接查询

Step 6: Apply Fix

步骤6：应用修复方案

Step 7: Verify Fix

步骤7：验证修复效果

Check deploy status

检查部署状态

Check for new errors

检查是否有新错误

Check metrics

检查指标

Quick Workflows

快速工作流

Quick Reference

快速参考

MCP Tools

MCP工具

Service Discovery

服务发现

Logs

日志

Metrics

指标

Database

数据库

Deployments

部署

Environment Variables

环境变量

CLI Commands (Fallback)

CLI命令（备选方案）

References

参考资料

Related Skills

相关技能