Debugging 'Service Not Found' and 404 Errors in FeathersJS

The Problem: Unreachable Services

A common frustration in FeathersJS development is the 404 Not Found error (via REST) or the 'Service Not Found' error (via Socket.io), even when the service code appears correct. This usually indicates a failure in the registration pipeline or a mismatch between the requested path and the internal service map.

Diagnostic Matrix

Use this table to identify the most likely cause based on the behavior of your application.

Symptom	Likely Cause	Diagnostic Focus
REST returns 404; Socket.io works	Express routing or middleware interference	Check app.use() order
Socket.io returns 'Service Not Found'; REST works	Transport configuration mismatch	Verify app.configure(socketio)
Both transports return 404/Not Found	Registration failure or path typo	Inspect app._services
405 Method Not Allowed	Service exists, but method is disabled	Check methods array in service

Step-by-Step Resolution Path

1. Verify Service Registration Order

FeathersJS processes requests based on the order of app.use() calls. If a generic middleware or a catch-all route is registered before your service, the request may be intercepted before it reaches the service handler.

Check: Ensure all app.use('/path', service) calls occur before any final error handlers or 404-catchers.

2. Inspect the Internal Service Map

The most reliable way to confirm a service is registered is to inspect the app._services object. This is the internal registry Feathers uses to route requests.

Run this check in a debugger or via a temporary diagnostic route (Admin permissions required):

// Run this in a node debugger or a temporary endpoint
console.log(Object.keys(app._services));

If your service key (e.g., 'messages') is missing from this list, the service was never successfully attached to the app instance.

3. Validate Path Exactness

Feathers paths are sensitive to trailing slashes and case depending on the underlying Express configuration. A request to /messages/ may fail if the service is registered as /messages.

Example Configuration:

// Correct registration
app.use('/messages', messageService);

// Potential failure points:
// Requesting: GET /messages/ (with trailing slash)
// Requesting: GET /Messages (case mismatch)

4. Audit Middleware Interference

Custom middleware placed before the service registration can accidentally terminate the request cycle. If a middleware does not call next(), the request never reaches the service.

Diagnostic Check: Temporarily comment out custom middleware preceding the service registration. If the service becomes reachable, the middleware is the culprit.

5. Check Transport-Specific Availability

If a service is available via REST but not Socket.io, ensure the Socket.io transport is configured after the services are registered. Feathers needs the services to be present in the app object to bind them to the socket transport.

// Correct Sequence
app.use('/messages', messageService);
app.configure(socketio);

Verification and Testing

To isolate the issue from the client-side library, use curl to test the REST endpoint directly. This removes Socket.io and client-side state from the equation.

Command:

# Run from your terminal
curl -X GET http://localhost:3030/messages

Expected Result: A 200 OK response with a JSON array. If this returns 404, the issue is in the Express/Server registration. If this returns 200 but the Socket.io client fails, the issue is in the Socket.io configuration.

Rollback and Recovery

If you modified the order of app.use() or changed paths and the application fails to boot or breaks other services:

• Revert the app.use() sequence to the previous known-working state.
• Verify that no duplicate paths were created, as Feathers will prioritize the first matching route.

Escalation Criteria

If the service appears in app._services and curl returns a 200 OK, but the client still receives a 404, the issue is likely not in the Feathers registration. Escalate your investigation to:

• Reverse Proxy: Check Nginx/Apache logs for path stripping or incorrect routing.
• CORS Policy: Ensure the browser isn't blocking the request before it reaches the server.
• Load Balancer: Verify that the request is hitting the specific instance where the service is deployed.