mcpField
Z
zeabur-port-mismatch

zeabur-port-mismatch

github.com/zeaburCloud & DevOps39173 installsUpdated 7w ago
Repository

About zeabur-port-mismatch

zeabur-port-mismatch is a skill for diagnosing port configuration problems in Zeabur services. It helps investigate timeouts, connection refusals, and 502 responses by checking forwarding, container listeners, and proxy settings.

Key features

  1. 01Check service port-forwarding status
  2. 02Inspect ports listening inside a container
  3. 03Compare proxy and container port settings
  4. 04Diagnose 502 errors from missing listeners
  5. 05Check and enable TCP port forwarding

Use cases

  1. 01Investigate connection timeouts after deployment
  2. 02Fix a mismatch between proxy and container ports
  3. 03Address 502 errors caused by no HTTP listener
  4. 04Check a TCP service that is unreachable externally

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/zeabur/agent-skills --skill zeabur-port-mismatch

After installing, type/zeabur-port-mismatchin Claude Code to confirm it loaded.

Details

From the project README

Zeabur Port Mismatch

Always use npx zeabur@latest to invoke Zeabur CLI. Never use zeabur directly or any other installation method. If npx is not available, install Node.js first.

Symptom

dial tcp 10.x.x.x:3000: i/o timeout
dial tcp 10.x.x.x:80: connection refused

Cause

Proxy expects service on port X, but service listens on port Y.

Diagnose

  1. Check port forwarding status and actual forwarded ports: 
    npx zeabur@latest service network --id SERVICE_ID
  2. Check what port the container is actually listening on: 
    npx zeabur@latest service exec --id SERVICE_ID -- netstat -tlnp
    (use the zeabur-deployment-logs skill to also check logs for port binding info)
  3. Check what port proxy expects (from Caddyfile/nginx.conf)
  4. Check what port container exposes (Dockerfile EXPOSE)

Common Mismatches

Proxy expectsContainer hasFix
:3000nginx default :80Change template port to 80
:80app on :3000Change template port to 3000

Fix in Template

Use the zeabur-template skill for full YAML reference on port configuration and portForwarding:

ports:
  - id: web
    port: 3000  # Match what container actually exposes
    type: HTTP

Check official Dockerfile for EXPOSE directive.

Headless Service (502 with no listener)

Symptom

Service is running (no crash), but proxy returns 502 Bad Gateway permanently.

Cause

Service does not listen on any HTTP port. Examples: chatbot gateways, background workers, message queue consumers. The template declares an HTTP port but nothing binds to it.

Fix

Add a lightweight HTTP health check server that runs in the background alongside the main process:

# Start before main process in startup script
# IMPORTANT: port must match spec.ports[].port in your template
python3 -c "
from http.server import HTTPServer, BaseHTTPRequestHandler
import json
class H(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header('Content-Type','application/json')
        self.end_headers()
        self.wfile.write(json.dumps({'status':'ok'}).encode())
    def log_message(self,*a): pass
HTTPServer(('0.0.0.0', 8080), H).serve_forever()
" &
exec my-headless-app

Port Forwarding Not Working

If a TCP service is deployed but not reachable externally:

  1. Check if port forwarding is enabled: 
    npx zeabur@latest service port-forward --id SERVICE_ID
  2. Enable it if disabled: 
    npx zeabur@latest service port-forward --id SERVICE_ID --enable
  3. Verify the forwarded endpoint: 
    npx zeabur@latest service network --id SERVICE_ID
# Output: proxy (TCP 8888) → 34.x.x.x:20143

Comments

Markdown supported