Troubleshooting

Common issues and how to resolve them when deploying the Tunnel Agent.

How routing works

Understanding the request flow helps diagnose issues:

Zihin Cloud sends a request to:
  tunnel.zihin.ai/t/{tenant_id}/{service}/{path...}
                     ──────────  ────────  ─────────
                     1. identifies  2. service  3. forwarded
                        the tunnel    name       to the agent

Agent receives: { service: "my-service", path: "/api/data" }
Agent resolves: "my-service" → base URL from config
Agent fetches:  GET https://internal-host:8080/api/data

The path from the cloud endpoint is appended to the base URL configured in the agent. The agent only provides host and port — the path comes from the request.

Error reference

404 — check the response body

Two different problems return 404 — the body tells them apart:

{"error":"No tunnel found for tenant"} — the agent is not connected.

Possible cause	Solution
Token (ztun_...) is incorrect or expired	Verify ZIHIN_TOKEN environment variable, request a new token
Agent is not running	Check with docker ps or systemctl status
Firewall blocking outbound WSS on port 443	Allow outbound HTTPS/WSS to tunnel.zihin.ai

{"error":"Service not found on tunnel: ..."} — the agent is connected, but no service with that name is registered.

The service name in zihin-agent.yml must match the {service} segment in the cloud endpoint URL:

Cloud endpoint: /t/{tenant}/crm/mcp/...
                             ───
Agent config:   services:
                  - name: crm    ← must match

401 — "Unauthorized"

Two possible sources — check the response body to distinguish:

Source	Response body	Agent logs	Cause
Tunnel Server	{"error":"Unauthorized"}	No log (request doesn't reach agent)	Invalid or missing Bearer token
Internal service	HTML or JSON from the service	Request completed { status: 401 }	Service credential (e.g., X-Api-Key) is invalid

If the response body is {"error":"Unauthorized"}, the issue is at the Tunnel Server level — verify that the cloud service is sending the correct Authorization: Bearer header.

502 — "Bad gateway"

The agent is connected, but the local fetch to the internal service failed.

Possible cause	Solution
Internal service URL is unreachable from the container	Test connectivity from inside the container (see below)
Self-signed SSL certificate	Mount the CA certificate and set NODE_EXTRA_CA_CERTS (see Getting Started)
Wrong port for the internal service	Verify the correct port
Internal service rejected the authentication token	Test the token directly with curl from the server

Diagnosis: Set log_level: debug in the agent config. The log line Fetch failed { code, error } shows the exact error.

504 — "Gateway timeout"

The internal service took longer than 30 seconds to start responding.

• Check the health of the internal service
• Avoid large queries without filters or pagination
• Real-time (SSE) responses are not subject to this limit from agent 1.2+ — they stream for as long as needed

406 — "Not Acceptable" (MCP services)

An Accept header in inject_headers is overriding the one the MCP client sends.

Remove Accept from the service's inject_headers and restart the agent — MCP clients already send the correct value. The agent logs a warning at startup when an Accept header is configured. Use inject_headers for credentials only.

Authentication errors (4001, 4003)

Code	Meaning	Solution
4001	Invalid or expired token	Check ZIHIN_TOKEN, request a new token
4002	Connection limit for your tunnel reached	Harmless — the extra connection waits and retries automatically. To use more, lower pool_size or ask the Zihin team to raise your tunnel's limit
4003	Tunnel not found on the server	Contact the Zihin team to verify provisioning

Diagnostic commands

Test from inside the Docker container

If the agent returns 502, test whether the container can reach the internal service:

# Test basic connectivity
docker exec zihin-tunnel wget -qO- --no-check-certificate https://INTERNAL_HOST:PORT/

# If this fails, the container can't reach the service.
# Solution: add network_mode: host to docker-compose.yml

Test the internal service directly (from SSH)

# Test the service endpoint with authentication
curl -sk -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://INTERNAL_HOST:PORT/api/endpoint

Enable debug logs

# In zihin-agent.yml
log_level: debug

Or via environment variable:

export ZIHIN_LOG_LEVEL=debug

Restart the agent after changing the log level. Remember to set it back to info after troubleshooting.

Common issues

Symptom	Likely cause	Solution
Reconnect loop	Firewall blocking outbound 443	Allow outbound HTTPS/WSS to tunnel.zihin.ai
Agent token is required	ZIHIN_TOKEN not set	Set the environment variable before starting
No services defined	YAML missing services block	Add at least one service to zihin-agent.yml
HOST_NOT_ALLOWED	Host policy restricts access	Contact the Zihin team to adjust allowed_hosts
RATE_LIMITED	Too many requests per minute	Reduce request frequency or request a limit increase
Response timeout	Internal service slow or unreachable	Verify the service URL is accessible from the agent machine

HTTP status codes — quick reference

HTTP	Meaning	Where it failed
200	Success	—
401	Invalid Bearer token or service credential	Cloud → Tunnel Server (check response body for {"error":"Unauthorized"}) or Agent → Internal service
404	Agent offline or tunnel doesn't exist	Tunnel Server
406	Accept header injected for an MCP service	Agent config — remove Accept from inject_headers
429	Rate limit exceeded	Tunnel Server or Agent
502	Agent connected, local fetch failed	Agent → Internal service
503	Too many simultaneous streaming (SSE) connections	Tunnel Server — close unused streams or contact the Zihin team
504	Timeout (>30s to first byte)	Agent → Internal service

Support

If you need help:

• Send logs with debug level to the Zihin team
• For a failing request, include the X-Tunnel-Request-Id response header — every tunnel response carries one, and it lets the team trace that exact request end to end
• Include the agent version: docker exec zihin-tunnel node dist/index.js --version
• Describe your setup: number of services, network type, corporate proxy (if any)