Field Report: Deploying n8n-claw on a self-hosted estate infrastructure — lessons learned

[frank-yann]

Field Report: Deploying n8n-claw on a self-hosted estate infrastructure — lessons learned

Context

I deployed n8n-claw on a self-hosted Debian 12 server (Mac Pro 5,1, 40GB RAM) as part of a larger home automation and estate management infrastructure. The stack runs alongside Home Assistant, Mosquitto MQTT, Zigbee2MQTT, Z-Wave JS UI, farmOS, and Nginx reverse proxy — all on a private LAN with a single external port (80/443) through Nginx.

The goal was to use n8n-claw's Telegram agent ("Charly") as a central AI assistant, and to build custom workflows for document management (Gmail → Claude analysis → Synology NAS upload → Notion database).

Setup was done via setup.sh on April 8, 2026, updated to v1.2.0 on April 9. Over two intensive days of debugging with Claude (Anthropic's AI assistant) and Claude Code (CLI), we discovered several undocumented behaviors that may help other users.

Environment

• n8n: 2.15.0 (Docker, via n8n-claw stack)
• Supabase PostgreSQL: 15.8.1 (port 5433)
• Nginx: reverse proxy on port 9444 (HTTPS) for n8n UI
• Telegram bot: webhook on port 443 (separate Nginx vhost)
• OS: Debian 12.13, kernel 6.1.0-44

Findings & Workarounds

1. "Connection lost" in the UI when behind a reverse proxy

Symptom: The n8n editor shows "connection lost" in a loop when accessed via https://domain:9444.

Root cause: n8n's WebSocket push validates the Origin header strictly. When the browser sends Origin: domain:9444 but n8n receives Host: domain (without port), it rejects the connection.

Fix:

N8N_PUSH_BACKEND=sse          # Switch from WebSocket to SSE
N8N_PROXY_HOPS=1              # Trust X-Forwarded-* headers
N8N_EDITOR_BASE_URL=https://domain:9444

Plus Nginx config:

proxy_buffering off;
proxy_cache off;
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;

Without proxy_buffering off, Nginx buffers the SSE stream and the client receives nothing — triggering "connection lost" even with SSE enabled.

2. Telegram webhook requires port 443/80/88/8443

Symptom: Agent workflow fails to activate with "Bad request - please check your parameters" in an exponential retry loop.

Root cause: N8N_WEBHOOK_URL was set to https://domain:9444. Telegram only accepts webhooks on ports 443, 80, 88, and 8443.

Fix: Decouple the editor URL from the webhook URL:

N8N_WEBHOOK_URL=https://domain        # Port 443 for Telegram
N8N_EDITOR_BASE_URL=https://domain:9444  # Port 9444 for UI

The existing Nginx location / on port 443 already proxied to n8n on localhost:5678, so no additional config was needed.

3. Credential IDs with cred- prefix cause UI warnings

Symptom: Nodes show orange/red triangle warnings even though credentials exist in the database.

Root cause: setup.sh creates some credentials with IDs like cred-sbtUNUheX6CLNq0U (with cred- prefix) while others use standard 16-char alphanumeric IDs. The n8n frontend validator may not recognize the prefixed format.

Workaround: We cloned the credential in PostgreSQL with a standard ID format (INSERT ... SELECT to copy the encrypted data blob), then updated all workflow references.

4. workflow_entity vs workflow_history — the hidden versioning system

Symptom: SQL updates to workflow_entity.nodes (e.g., credential ID replacements) have no effect on running workflows.

Root cause: n8n-claw uses workflow_entity.activeVersionId which points to a row in workflow_history. Active workflows execute from workflow_history, not from workflow_entity.nodes. Any direct SQL modification must be applied to BOTH tables.

This is the most critical finding. We lost several hours before discovering this. It would be extremely helpful to document this in the README or setup output.

5. GET /api/v1/credentials returns Forbidden

Symptom: The n8n REST API returns 403 on the credentials endpoint with the API key generated during setup.

Workaround: Read credentials directly from PostgreSQL (credentials_entity table). The encrypted data can be cloned between credentials without needing N8N_ENCRYPTION_KEY.

6. httpRequest nodes destroy binary data

Symptom: When building a workflow chain like Gmail Trigger → HTTP Request (Claude API) → HTTP Request (NAS upload), the file attachments from Gmail are lost after the first HTTP Request node.

Root cause: This is by design — each httpRequest node replaces the item's data (including binaries) with its own HTTP response. But it's not obvious when designing workflows visually.

Solution we adopted: Split into two workflows connected by a Supabase queue table. Workflow A (detector) analyzes emails without touching binaries. Workflow B (processor) re-fetches the email with attachments directly from Gmail API when processing the queue. This completely avoids the binary propagation problem.

7. Claude API responses wrapped in markdown fences

Symptom: JSON.parse() on Claude's response fails silently (returns undefined), causing the IF node to always route to the "false" branch.

Root cause: Claude (Anthropic API) often wraps JSON responses in ```json ... ``` fences, even when instructed not to.

Fix: Belt-and-suspenders approach:

1. Add "Do NOT wrap in markdown fences" to the prompt
2. Strip fences before parsing: .replace(/```json\n?/g,'').replace(/```\n?/g,'').trim()

8. Code node typeVersion 2 has a 60-second timeout

Symptom: A simple Code node that copies binary data from one node to another times out after 60 seconds.

Root cause: Code node typeVersion 2 uses n8n's Task Runner which has a hard 60-second timeout. typeVersion 1 executes inline in the main process without timeout.

Recommendation: Use typeVersion 1 for simple data manipulation tasks. Document the timeout limitation of typeVersion 2.

9. Gmail Trigger has only one output

Symptom: Connecting a node to Gmail Trigger's output index 1 results in null data.

Root cause: gmailTrigger has a single output (index 0). Attempting to use output[1] for a Y-branch produces nothing.

Fix: Connect multiple nodes to output[0] (n8n supports multiple connections from a single output).

Architecture recommendation for complex workflows

Based on our experience, we recommend against building monolithic workflows that chain multiple HTTP requests with binary data. Instead, use a modular queue-based architecture:

• Workflow A (Detector): lightweight, no binaries — analyzes emails with Claude, stores results in a Supabase queue table
• Workflow B (Processor): reads the queue, re-fetches emails with fresh attachments, uploads to NAS, creates Notion entries
• Workflow C (Batch scanner): manual trigger, processes historical emails through the same queue
• Workflow D (Monitor): daily health checks, version monitoring, Telegram alerts

This pattern cleanly separates concerns and avoids all binary propagation issues.

Suggested improvements for n8n-claw

1. Document the workflow_history versioning in README — this is the Welcome to n8n-claw Discussions! #1 gotcha for anyone modifying workflows via API or SQL
2. Use standard credential ID format (no cred- prefix) to avoid UI warnings
3. Add a troubleshooting section for reverse proxy setups (especially the SSE + proxy_buffering combination)
4. Document the Telegram port restriction (443/80/88/8443) prominently in setup output
5. Include a CREDENTIALS.md that lists credential IDs after setup, for reference when building custom workflows

Thanks

n8n-claw is an impressive project — having a fully self-hosted AI agent running on Telegram with memory, MCP tools, and sub-agents is remarkable for a community project. These findings are shared in the spirit of making it even better for the next person who deploys it.

---

Deployed at Chateau de Charly, Nievre, France — a self-hosted agricultural estate with 6 Linux servers, home automation, music studio, and now an AI agent managing supplier invoices.

[dankerthrone]

I gotta say I don't even understand half of what you're describing, but I love that you shared your experiences! Thanks!