Getting Started

Troubleshooting

Common Sockudo setup and integration issues.

Connection Fails Immediately

Checklist:

Server is reachable: curl http://host:6001/up
App key exists and app is enabled.
Client points to wsHost/wsPort (or wssPort + TLS) correctly.
Reverse proxy forwards WebSocket upgrade headers.

`400`/`401` on HTTP API Publish

/apps/{appId}/events and related routes require Pusher-style signed query params:

auth_key
auth_timestamp
auth_version
body_md5 (required for non-empty POST body)
auth_signature

Also ensure clock skew is under 10 minutes.

For private-* and presence-*, return auth from your auth endpoint.
For presence-*, include valid channel_data JSON with user_id.
Signature must use exact channel name and socket ID from request.

`/up` Returns `ERROR`

/up returns 503 if critical components fail (adapter/cache health checks).
Check server logs and dependent services (Redis/NATS/SQL).

Messages Arrive but Delta/Filter Features Do Not Work

This is expected with plain pusher-js or Laravel Echo clients.

Use @sockudo/client for:

subscribe(channel, filter)
Automatic pusher:delta reconstruction
Per-subscription delta settings

Metrics Not Available

Enable metrics: METRICS_ENABLED=true
Confirm metrics listener: METRICS_HOST + METRICS_PORT (default 9601)
Query metrics endpoint directly: http://host:9601/metrics

Migration

Move from hosted Pusher or self-hosted alternatives to Sockudo with minimal client changes.

Configuration

Server config structure, load order, and runtime defaults.