Diagnosing Real-Time Event Failures in FeathersJS

The Problem: Silent Socket Events

A common failure pattern in FeathersJS occurs when REST API calls succeed (returning 200 or 201 status codes) and database records update correctly, but connected WebSocket clients never receive the corresponding created, updated, patched, or removed events. The client-side listeners—such as app.service('messages').on('created', callback)—remain silent despite the server successfully processing the request.

Diagnostic Matrix

Use this table to identify the likely cause based on the scope of the failure.

Symptom	Likely Cause	Primary Check
All clients miss all events	Channel configuration missing	Verify app.configure(channels()) call
Only specific users miss events	Channel membership failure	Check app.channel('name').join(connection)
Works locally, fails in production	Load balancer / Sticky sessions	Verify WebSocket affinity in proxy config
Authenticated users miss events	Hook execution order	Ensure authenticate('jwt') runs before channel join
Intermittent misses in multi-node	Missing Pub/Sub adapter	Check for @feathersjs/redis configuration

Step-by-Step Diagnostic Workflow

1. Verify Transport and Channel Setup

Feathers requires the channels plugin to be configured after the transport (Socket.io) is initialized. If the order is reversed or the call is missing, the server cannot map service events to socket connections.

// Correct Order
app.configure(socketio());
app.configure(channels());

2. Inspect Service Event Configuration

By default, Feathers services emit events. However, if you have customized the events array in your service options, ensure the required events are listed. If you are using a custom service class that extends the base Service, verify that super.emit() is being called.

3. Audit Connection and Membership

If events only fail for authenticated users, the connection may not be joined to the correct channel. In Feathers v5 (Dove), app.channel() returns a Channel instance. You must explicitly join the connection to a channel, typically within an on('connection') handler or an authentication hook.

// Example: Joining a channel on connection
app.io.on('connection', (connection) => {
  // Join the anonymous channel by default
  app.channel('anonymous').join(connection);
});

Risk: In v5, app.channels is a Map. Attempting to access channels via app.channels['name'] (the v4 pattern) will fail silently.

4. Validate Multi-Node Synchronization

If your app runs on multiple server instances, a client connected to Server A will not receive an event emitted by Server B unless a Pub/Sub adapter is used. Without this, events are local to the process memory.

Configuration Example: Use @feathersjs/redis to synchronize events across nodes.

// In your app configuration
const redis = new Redis();
app.configure(channels({ 
  redis 
}));

Verification and Testing

To confirm the fix, run these checks in order:

• Version Alignment: Run npm ls @feathersjs/feathers @feathersjs/socketio to ensure all major versions match. Mismatched versions often cause silent handshake failures.
• Raw Packet Inspection: On the client, use the Socket.io debug listener to see if packets are arriving but being ignored by the Feathers client: app.io.on('*', (event, ...args) => console.log('Raw WS Event:', event, args));
• Membership Audit: Log the size of your channels on the server to ensure users are actually joined: console.log('Anonymous count:', app.channel('anonymous').connections.size);
• Redis Monitor: If using Redis, run redis-cli MONITOR. You should see PUBLISH feathers/events <payload> whenever a service update occurs.

When to Escalate

If the above steps do not resolve the issue, escalate to your infrastructure or platform team if you encounter these specific conditions:

• Proxy Blocks: WebSocket upgrade requests return 400 or 403 errors only when behind a corporate proxy or WAF.
• Memory Leaks: connection objects are not being cleaned up on disconnect, leading to climbing memory usage (profile with clinic.js).
• Redis Cluster Issues: Events fail specifically when using AWS ElastiCache with Cluster Mode enabled, which requires specific client-side sharding awareness.

Rollback Procedure

If changes to the channel configuration or Redis adapter cause instability:

1. Remove the @feathersjs/redis configuration from the channels() call.
2. Revert the app.configure order to the previous known-working state.
3. Restart the Node.js process to clear the in-memory channel Map.