troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ContextVM Troubleshooting

ContextVM故障排查

Diagnose and resolve common ContextVM issues.

诊断并解决ContextVM的常见问题。

Quick Diagnostic Checklist

快速诊断清单

When something isn't working, verify these fundamentals:

Relay Connectivity: Can you connect to the configured relays?
Key Permissions: Is the private key valid and properly formatted?
Network Access: Does the device have outbound internet access?
Server State: Is the target server running and accessible?
Encryption: If using encryption, does the server support it?

当出现问题时，请先验证以下基础项：

中继连接性：能否连接到配置的中继？
密钥权限：私钥是否有效且格式正确？
网络访问：设备是否有对外互联网访问权限？
服务器状态：目标服务器是否正在运行且可访问？
加密设置：如果使用加密，服务器是否支持该加密方式？

Connection Issues

连接问题

Symptom: Cannot connect to server

症状：无法连接到服务器

Check relay connectivity:

bash

undefined

检查中继连接性：

bash

undefined

Test relay WebSocket connection

wscat -c wss://relay.contextvm.org


**Common causes:**
- Relay URL is incorrect or offline
- Firewall blocking WebSocket connections (port 443)
- Server public key is wrong or server is not running

**Solutions:**
- Try multiple relays: `wss://relay.contextvm.org`, `wss://nos.lol`
- Verify server is running and announced (if public)
- Check server logs for incoming connections

wscat -c wss://relay.contextvm.org


**常见原因：**
- 中继URL不正确或中继已下线
- 防火墙阻止了WebSocket连接（端口443）
- 服务器公钥错误或服务器未运行

**解决方案：**
- 尝试多个中继：`wss://relay.contextvm.org`、`wss://nos.lol`
- 验证服务器是否正在运行且已公开宣告（如果是公开服务器）
- 检查服务器日志中的入站连接记录

Symptom: Connection timeout

症状：连接超时

Diagnose:

Client sends request but no response received
Timeout occurs after 5-30 seconds

Common causes:

Server is offline or not connected to relays
Request event not reaching server (relay issues)
Response event not reaching client (filter issues)

Solutions:

Verify server is connected to same relays as client
Check relay subscriptions are active
Increase timeout for slow operations
Verify response filter includes correct
```
authors
```
and
```
#e
```
tags

诊断：

客户端发送请求但未收到响应
5-30秒后出现超时

常见原因：

服务器已下线或未连接到中继
请求事件未送达服务器（中继问题）
响应事件未送达客户端（过滤规则问题）

解决方案：

验证服务器是否与客户端连接到相同的中继
检查中继订阅是否处于活跃状态
为慢速操作增加超时时间
验证响应过滤规则包含正确的
```
authors
```
和
```
#e
```
标签

Relay Problems

中继故障

Symptom: Events not propagating

症状：事件未传播

Check event publication:

Verify event was published successfully (check for OK response from relay)
Query relay directly for the event ID

Common causes:

Rate limiting by relay
Event rejected (invalid signature, wrong kind)
Relay not storing ephemeral events (kind 25910 is ephemeral)

Solutions:

Connect to multiple relays for redundancy
Verify event signature is valid
For kind 25910: these are ephemeral, subscriptions must be active before publishing

检查事件发布情况：

验证事件是否发布成功（检查中继返回的OK响应）
直接向中继查询该事件ID

常见原因：

中继的速率限制
事件被拒绝（签名无效、类型错误）
中继不存储临时事件（类型25910为临时事件）

解决方案：

连接到多个中继以实现冗余
验证事件签名是否有效
对于类型25910：此类为临时事件，必须在发布前激活订阅

Symptom: Missing responses

症状：缺少响应

Check subscription filters:

json

{
  "kinds": [25910],
  "authors": ["<server-pubkey>"],
  "#e": ["<request-event-id>"]
}

Common causes:

Filter doesn't match response event
Response
```
e
```
tag doesn't reference correct request ID
Subscription closed before response arrives

Solutions:

Ensure subscription is open before sending request
Verify
```
authors
```
filter matches server pubkey exactly
Check response
```
e
```
tag references your request ID

检查订阅过滤规则：

json

{
  "kinds": [25910],
  "authors": ["<server-pubkey>"],
  "#e": ["<request-event-id>"]
}

常见原因：

过滤规则与响应事件不匹配
响应的
```
e
```
标签未引用正确的请求ID
响应到达前订阅已关闭

解决方案：

确保在发送请求前订阅处于开启状态
验证
```
authors
```
过滤规则与服务器公钥完全匹配
检查响应的
```
e
```
标签是否引用了你的请求ID

Encryption Issues (CEP-4)

加密问题（CEP-4）

Symptom: Cannot decrypt responses

症状：无法解密响应

Check encryption support:

Verify server announcement has
```
support_encryption
```
tag
Or attempt encrypted first, fall back to unencrypted

Common causes:

Client trying to decrypt with wrong key
Server not encrypting responses
NIP-44 implementation mismatch

Solutions:

Verify you're using correct private key for decryption
Check server supports encryption via announcement
Ensure NIP-44 library is correctly implemented

检查加密支持情况：

验证服务器宣告是否包含
```
support_encryption
```
标签
或者先尝试加密方式，失败后回退到未加密方式

常见原因：

客户端使用错误的密钥进行解密
服务器未对响应进行加密
NIP-44实现不匹配

解决方案：

验证你使用的解密私钥是否正确
通过服务器宣告检查其是否支持加密
确保NIP-44库已正确实现

Symptom: Server rejects encrypted requests

症状：服务器拒绝加密请求

Check gift wrap structure:

json

{
  "kind": 1059,
  "pubkey": "<random-pubkey>",
  "tags": [["p", "<server-pubkey>"]],
  "content": "<nip44-encrypted-kind-25910>"
}

Common causes:

Server doesn't support encryption
Malformed gift wrap
Wrong recipient in
```
p
```
tag

Solutions:

Check server announcement for
```
support_encryption
```
Verify gift wrap structure matches NIP-59
Ensure
```
p
```
tag points to server's public key

检查礼品包装结构：

json

{
  "kind": 1059,
  "pubkey": "<random-pubkey>",
  "tags": [["p", "<server-pubkey>"]],
  "content": "<nip44-encrypted-kind-25910>"
}

常见原因：

服务器不支持加密
礼品包装格式错误
```
p
```
标签中的接收方错误

解决方案：

检查服务器宣告中的
```
support_encryption
```
字段
验证礼品包装结构是否符合NIP-59规范
确保
```
p
```
标签指向服务器的公钥

Authentication Failures

认证失败

Symptom: Server rejects requests

症状：服务器拒绝请求

Check authorization:

Verify client public key is whitelisted (if server uses whitelist)
Check server logs for rejection reasons

Common causes:

Client not in
```
allowedPublicKeys
```
list
Server requires payment (not implemented in basic troubleshooting)
Invalid request format

Solutions:

Contact server operator to add your pubkey to whitelist
Verify request follows MCP JSON-RPC format
Check server capability exclusions (some methods may be public)

检查授权情况：

验证客户端公钥是否在白名单中（如果服务器使用白名单机制）
检查服务器日志中的拒绝原因

常见原因：

客户端不在
```
allowedPublicKeys
```
列表中
服务器要求付费（基础故障排查中未实现）
请求格式无效

解决方案：

联系服务器管理员将你的公钥添加到白名单
验证请求是否遵循MCP JSON-RPC格式
检查服务器功能排除项（部分方法可能为公开访问）

Gateway/Proxy Issues

网关/代理问题

Symptom: Gateway cannot connect to MCP server

症状：网关无法连接到MCP服务器

Check:

MCP server command is correct and executable
Server starts successfully and listens on expected transport
No port conflicts

Solutions:

Test MCP server independently first
Verify gateway command path is correct
Check gateway logs for spawn errors

检查项：

MCP服务器命令是否正确且可执行
服务器是否成功启动并在预期的传输方式上监听
无端口冲突

解决方案：

先独立测试MCP服务器
验证网关命令路径是否正确
检查网关日志中的启动错误

Symptom: Proxy cannot connect to ContextVM server

症状：代理无法连接到ContextVM服务器

Check:

Server public key is correct
Server is running and connected to relays
Client can reach relays

Solutions:

Verify server pubkey (check for typos)
Ensure server is actually running
Test relay connectivity from client machine

检查项：

服务器公钥是否正确
服务器是否正在运行且已连接到中继
客户端能否访问中继

解决方案：

验证服务器公钥（检查是否有拼写错误）
确保服务器确实在运行
从客户端机器测试中继连接性

Common Error Patterns

常见错误模式

"Event not found" or timeout

"Event not found"或超时

Request event ID doesn't exist
Subscription filter too restrictive
Relay dropped connection

请求事件ID不存在
订阅过滤规则过于严格
中继断开连接

"Invalid signature"

Private key doesn't match claimed public key
Event was modified after signing
Signing implementation error

私钥与声明的公钥不匹配
签名后事件被修改
签名实现错误

"Method not found"

Request method name is wrong
Server doesn't support that capability
Server hasn't announced that tool/resource/prompt

请求方法名称错误
服务器不支持该功能
服务器未宣告该工具/资源/提示词

"Connection refused"

Relay is down or URL is wrong
Firewall blocking connection
Incorrect WebSocket URL format

中继已下线或URL错误
防火墙阻止了连接
WebSocket URL格式不正确

Debugging Techniques

调试技巧

Enable Logging

启用日志

Most ContextVM components support debug logging:

bash

LOG_LEVEL=debug gateway-cli ...
LOG_LEVEL=debug proxy-cli ...

大多数ContextVM组件支持调试日志：

bash

LOG_LEVEL=debug gateway-cli ...
LOG_LEVEL=debug proxy-cli ...

Monitor Relay Traffic

监控中继流量

Subscribe to all events from your pubkey to see what's happening:

json

{
  "kinds": [25910, 1059],
  "authors": ["<your-pubkey>"]
}

订阅你的公钥的所有事件以查看情况：

json

{
  "kinds": [25910, 1059],
  "authors": ["<your-pubkey>"]
}

Test Components Independently

独立测试组件

Test relay: Connect with WebSocket client
Test server: Use SDK or direct Nostr events
Test client: Connect to known working server

测试中继：使用WebSocket客户端连接
测试服务器：使用SDK或直接Nostr事件
测试客户端：连接到已知正常工作的服务器

Use contextvm.org for Remote Server Testing

使用contextvm.org进行远程服务器测试

The contextvm.org website provides a valuable debugging tool for testing ContextVM servers. You can use it to:

Connect to any publicly announced ContextVM server
Inspect available tools, resources, and prompts
Execute tool calls directly from the browser
Verify server announcements and capabilities
Test encryption support (CEP-4)

When to use:

Verifying your server is properly announced and accessible
Testing tool execution without writing client code
Debugging connectivity issues from an external client perspective
Confirming encryption/decryption works correctly

contextvm.org网站提供了一个有价值的调试工具，用于测试ContextVM服务器。你可以用它来：

连接到任何公开宣告的ContextVM服务器
检查可用的工具、资源和提示词
直接从浏览器执行工具调用
验证服务器宣告和功能
测试加密支持（CEP-4）

使用场景：

验证你的服务器是否已正确宣告且可访问
无需编写客户端代码即可测试工具执行
从外部客户端视角调试连接问题
确认加密/解密是否正常工作

Debug STDIO Servers with MCP Inspector

使用MCP Inspector调试STDIO服务器

For debugging local STDIO-based MCP servers (used with gateways), the MCP Inspector is the recommended tool.

Installation and usage:

bash

undefined

对于调试基于STDIO的本地MCP服务器（与网关配合使用），推荐使用MCP Inspector工具。

安装与使用：

bash

undefined

Run inspector with your STDIO server

npx @modelcontextprotocol/inspector node path/to/server.js

For Python servers

npx @modelcontextprotocol/inspector uv --directory path/to/server run package-name


**What it provides:**
- Interactive UI for testing tools, resources, and prompts
- View request/response JSON-RPC messages
- Verify server initialization and capability negotiation
- Test edge cases and error handling

npx @modelcontextprotocol/inspector uv --directory path/to/server run package-name


**提供的功能：**
- 用于测试工具、资源和提示词的交互式UI
- 查看请求/响应JSON-RPC消息
- 验证服务器初始化和功能协商
- 测试边缘情况和错误处理

Verify Event Structure

验证事件结构

Use a Nostr event validator to check:

Valid JSON in content
Correct event kind
Proper tag structure
Valid signature

使用Nostr事件验证器检查：

content中的JSON是否有效
事件类型是否正确
标签结构是否规范
签名是否有效

References

参考资料

```
../overview/references/ceps.md
```
— CEP-4 encryption details
```
../overview/references/protocol-spec.md
```
— Event structure

../client-dev/references/nostr-way-without-sdks.md

— Raw Nostr implementation

../server-dev/references/debugging-inspector.md

— MCP Inspector usage

NIP-44 — Encryption specification
NIP-59 — Gift wrap specification

```
../overview/references/ceps.md
```
— CEP-4加密细节
```
../overview/references/protocol-spec.md
```
— 事件结构

../client-dev/references/nostr-way-without-sdks.md

— 原生Nostr实现

../server-dev/references/debugging-inspector.md

— MCP Inspector使用方法

NIP-44 — 加密规范
NIP-59 — 礼品包装规范