ContextVM Troubleshooting

Quick Diagnostic Checklist

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

Connection Issues

Symptom: Cannot connect to server

# Test relay WebSocket connection
wscat -c wss://relay.contextvm.org

• Relay URL is incorrect or offline
• Firewall blocking WebSocket connections (port 443)
• Server public key is wrong or server is not running

• Try multiple relays:

  wss://relay.contextvm.org

  ,

  wss://nos.lol

• Verify server is running and announced (if public)
• Check server logs for incoming connections

Symptom: Connection timeout

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

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

• 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

Relay Problems

Symptom: Events not propagating

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

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

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

Symptom: Missing responses

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

• Filter doesn't match response event
• Response

  e

  tag doesn't reference correct request ID
• Subscription closed before response arrives

• Ensure subscription is open before sending request
• Verify

  authors

  filter matches server pubkey exactly
• Check response

  e

  tag references your request ID

Encryption Issues (CEP-4)

Symptom: Cannot decrypt responses

• Verify server announcement has

  support_encryption

  tag
• Or attempt encrypted first, fall back to unencrypted

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

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

Symptom: Server rejects encrypted requests

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

• Server doesn't support encryption
• Malformed gift wrap
• Wrong recipient in

  p

  tag

• Check server announcement for

  support_encryption

• Verify gift wrap structure matches NIP-59
• Ensure

  p

  tag points to server's public key

Authentication Failures

Symptom: Server rejects requests

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

• Client not in

  allowedPublicKeys

  list
• Server requires payment (not implemented in basic troubleshooting)
• Invalid request format

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

Gateway/Proxy Issues

Symptom: Gateway cannot connect to MCP server

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

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

Symptom: Proxy cannot connect to ContextVM server

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

• 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

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

"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

Debugging Techniques

Enable Logging

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

Monitor Relay Traffic

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

Test Components Independently

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

Use contextvm.org for Remote Server Testing

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

• 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

Debug STDIO Servers with MCP Inspector

# 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

• 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

Verify Event Structure

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

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