Diagnosing Moleculer Action Not Found Errors Due to Version or Registration Issues

Recognizable condition

When invoking a Moleculer action you receive an HTTP 404 or the framework error "Action not found" even though the action is clearly defined in the service schema.

Cause / diagnostic table

Possible cause	What you might see
Service version mismatch	Caller expects version X but the registered service advertises version Y.
Service not loaded / transporter failure	Broker logs show "Service not found" or transporter disconnect warnings.
Namespace or action name typo	Action name in the request differs (extra spaces, wrong case) from the schema.
Stale cache in API gateway or client	Gateway returns 400/404 despite the broker listing the action.
Transport serializer mismatch	Protobuf vs JSON on different nodes corrupts the action name during serialization.

Ordered checks

1. List local services – In any service file or REPL, run:

   // Run inside a Moleculer service (e.g., in an action)
   const services = this.broker.getLocalServices();
   console.log(JSON.stringify(services, null, 2));

   Verify that the target service appears and its actions list contains the expected action name. Required permission: access to the broker instance (no special rights). Risk: none; read‑only.
2. Check transporter status – Look at broker logs or subscribe to transit events:

   this.broker.transit.on('disconnect', () => console.log('Transporter disconnected'));
   this.broker.transit.on('connect', () => console.log('Transporter connected'));

   Ensure the transporter (NATS, Redis, MQTT, etc.) shows a connected state. Where to run: in the service’s started lifecycle or via the broker’s REPL. Risk: none.
3. Confirm version metadata – Inspect the service schema:

   // In the service definition
   const { Service } = require('moleculer');
   module.exports = new Service({
     name: 'math',
     version: '1.0',   // <-- check this
     actions: { add: { /* ... */ } }
   });

   Compare this version with the value used by the caller (e.g., in this.broker.call('math.v2.add', ...)). Risk: changing version in production may cause temporary mismatches for existing clients.
4. Scan broker logs for registration messages – Grep for:

   Service registered: math@v1.0
   Service not found: math@v2.0

   Presence of "Service not found" indicates a version or name mismatch. Risk: none.
5. Validate API gateway forwarding – If using an API gateway (e.g., Moleculer‑Web), check the route definition:

   // moleculer-web config
   routes: [
     {
       path: '/api',
       whitelist: [
         { action: 'math.add', version: '1.0' }   // <-- ensure version matches
       ]
     }
   ];

   Ensure the gateway forwards the exact action name and version. Risk: misconfiguration can silently drop requests.

Fixes tied to findings

• Version mismatch – Align service.version across provider and consumer, or omit the version to let the broker resolve to the latest. Example: Change caller from this.broker.call('math.v2.add', ...) to this.broker.call('math.add', ...) if the service defines version: '1.0'.
• Service not loaded – Restart the node, verify transporter connection (check credentials, port, cluster settings). For NATS, ensure nats://user:pass@host:4222 is identical on all nodes.
• Namespace/action typo – Correct the action name in the caller, remove extra spaces, and match case exactly as defined in the schema.
• Stale cache – If using Moleculer‑Web or a custom gateway, set cache: false on the action or clear the gateway’s Redis/Memory cache.
• Serializer mismatch – Standardize the transporter serializer (e.g., transporter: { type: 'JSON', options: {} }) on every node. Do not mix Protobuf and JSON unless you have explicit mapping.

Verification

After applying a fix, confirm the action is reachable:

1. Call the action directly via the broker:

   this.broker.call('math.add', { a: 5, b: 3 })
         .then(res => console.log('Result:', res))
         .catch(err => console.error('Error:', err));

   Expect a successful response (status 200 or the expected data).
2. Re‑run this.broker.getLocalServices() and verify the service lists the action with the correct version.
3. If using an API gateway, send an HTTP request to the endpoint (e.g., GET /api/math/add?a=5&b=3) and validate the response matches the expected schema.

Escalation criteria

If the error persists after completing the checks and fixes:

• Enable broker debug logging: loggerLevel: 'debug' in the broker options.
• Capture the full request/response payloads (including headers).
• Reproduce the issue in a minimal test project (single broker, one service, one caller).
• If still unresolved, open an issue on the Moleculer GitHub repository with logs, version info, and the minimal reproduction steps.

Limitations

This guide assumes the broker process is running and the transporter is functional. It does not cover network‑level firewalls or DNS resolution problems that prevent nodes from reaching each other.

Practical way to check the result

Run the verification steps above; a successful broker.call response or a correct HTTP reply from the gateway confirms that the action is now reachable.