Diagnosing Moleculer Transport Failures: A Step‑by‑Step Guide

Recognizable Condition

When a Moleculer service boots, the broker emits a fatal error and exits with a stack trace that includes "Moleculer: Transport error" or "Cannot connect to transport". The process never reaches the started event, and no services are registered.

Common Causes & Quick Diagnostic Table

Cause	What to Look For
Missing transport module	Stack trace references require(...) failure or module not found
Invalid transport configuration object	Config contains unknown keys or missing required fields (e.g., url, port)
Unconfigured or malformed environment variables	Logs show undefined REDIS_URL or similar
Broker unreachable (network or broker down)	Connection timeout errors, no Transport connected log
Custom transport plugin missing or mis‑exported	Stack trace references plugin path or export

Ordered Checks & Fixes

1. Verify Moleculer Version

   Run moleculer --version to confirm you are on 0.14+ where transport options are nested in broker.transport. Older syntax (transport: { type: ... }) will silently fail.

2. Inspect the Broker Configuration File

   Open config.js (or the file you pass via -c) and locate the transport section. Example for Redis:

   module.exports = {
       name: "my‑service",
       transport: {
           type: "redis",
           options: {
               url: process.env.REDIS_URL || "redis://127.0.0.1:6379"
           }
       }
   };
   

   Print the resolved config before initializing the broker:

   const config = require("./config");
   console.log(JSON.stringify(config, null, 2));
   

3. Check Environment Variables

   From the host or container, run:

   env | grep -E 'REDIS_URL|NATS_URL|MQTT_URL'
   

   Missing or malformed values (e.g., REDIS_URL=redis://:password@localhost) will cause connection failures.

4. Test Network Connectivity to the Broker

   Use telnet or nc to confirm the port is reachable:

   nc -vz redis-host 6379
   

   Failure indicates a firewall or broker outage.

5. Enable Detailed Debug Logging

   Start Moleculer with:

   DEBUG=moleculer:* moleculer -c config.js
   

   Look for logs such as Transport connecting to redis://… and Transport connected. A missing connected log signals handshake failure.

6. Validate Custom Transport Plugin

   If you use a custom transport (e.g., moleculer-custom-transport), ensure it is installed:

   npm ls moleculer-custom-transport
   

   Check that the plugin exports a class extending MoleculerTransport. A missing export will throw a runtime error.

7. Confirm Broker Credentials & TLS Settings

   Match the broker’s username/password, client certificates, and TLS options with those in transport.options. Mismatches often surface as authentication errors that look like network failures.

8. Apply the Fix & Verify

   After correcting the identified issue, restart the service:

   pm2 reload my‑service
   

   Check the logs for Broker started and the started event. If the service registers services, the transport is functioning.

Escalation Criteria

If all checks above resolve no issue, consider:

• Consulting the broker’s own logs (Redis, NATS, MQTT) for connection attempts.
• Running a minimal Moleculer node with only the transport configured to isolate the problem.
• Reviewing Docker network policies or host firewall rules if the service runs in a container.
• Upgrading Moleculer or the transport plugin to the latest stable release.

Limitations & Practical Checks

• The guide assumes a single broker per service; multi‑broker setups add complexity.

• If the broker uses IPv6, replace nc with nc -vz -6 or use telnet6.

• Debug logs can be noisy; filter with grep "Transport" if necessary.

To confirm resolution, run moleculer -c config.js --verbose and watch for the broker started message without preceding errors.