Common Issues

Quick diagnostic checklists and code-level solutions for common protocol compilation and network routing anomalies.

ECONNREFUSED issue

Underlying Cause

Server is not running or client bound to the wrong TCP port.

Recommended Fix

Verify server.listen() was executed successfully. Confirm port parameters are identical in both server and client configurations.

Frame parse error (code 100) issue

Underlying Cause

Magic segment byte mismatch — indicates connection of a non-AfterLink raw TCP/HTTP client.

Recommended Fix

Ensure all peer endpoints utilize the @afterlink/client or @afterlink/browser SDKs. Reject unencrypted raw socket scanners.

Validation error (code 422) issue

Underlying Cause

Frame payload buffer structure does not conform to the registered Zod verification schema.

Recommended Fix

Inspect client transmission models. Use z.any() to skip schema validation for optional payload fields during development stages.

Reference Code

z.object({ name: z.string(), email: z.string().email() })

JWT auth fails (code 401) issue

Underlying Cause

Handshake token signature secret mismatch or expiration claim threshold exceeded.

Recommended Fix

Verify that both client and server nodes share the exact base64 secret key. Check expiration (exp) attributes.

ECONNRESET on Windows systems issue

Underlying Cause

Windows Firewall configuration blocks inbound node socket execution paths.

Recommended Fix

Add an explicit Windows Inbound Firewall Allowance Rule for node.exe executable on the configured AfterLink port.

High memory accumulation issue

Underlying Cause

Zombie socket connections accumulating on server due to client network dropouts.

Recommended Fix

Configure explicit connection limitations and idle heartbeats inside your Server constructor parameters.

Reference Code

new Server({ port: 4000, maxConnections: 500, idleTimeout: 60000 })

Pub/Sub messages out of order issue

Underlying Cause

Transmission sequences are only guaranteed within single matching channel groups.

Recommended Fix

Structure multi-topic message delivery pipelines using sequence numbers or timestamps if order across topics is critical.

Browser client not connecting issue

Underlying Cause

WebSocket bridge gateway is disabled or missing CORS configuration on backend.

Recommended Fix

Activate WebSocket support in server options and bind client via ws:// URIs instead of native TCP afterlink:// schemes.

Reference Code

new Server({ port: 4000, browser: { enabled: true, corsOrigins: ["*"] } })

Route not found (code 404) issue

Underlying Cause

server.on() string identifier does not match incoming client.request() method.

Recommended Fix

Route strings are exact, case-sensitive match keys. Check casing, spacing, and route spelling on both endpoints.

afterlink CLI not found issue

Underlying Cause

The global development inspector package is not loaded into the system environment paths.

Recommended Fix

Install the AfterLink command-line tools distribution globally through npm.

Reference Code

npm install -g @afterlink/cli

← Code Examples