Troubleshooting

Dashboard route does not load

Symptoms: /_devtools returns a normal application response or 404.

Check: Mount devtools.middleware(req, res, next) before application routes and use the same server port in the dashboard URL.

No requests appear

Symptoms: The dashboard loads but the request list is empty.

Check: Confirm await devtools.start() completed before creating the server and that the request is not itself a /_devtools route.

Database or Redis spans are missing

Check: Preload the initialization module before importing mongodb, pg, mysql2, or ioredis. Confirm the operation executes during an active request. See the relevant integration guide.

Authentication fails

Confirm SERVER_DEVTOOLS_USERNAME and SERVER_DEVTOOLS_PASSWORD are set in the process that starts the application. Restart after changing them.

Encryption configuration fails

The key must be base64 that decodes to exactly 32 bytes. A missing key or a key with the wrong length throws during construction.

ESM and CommonJS problems

The package is CommonJS at its root export and provides a NestJS subpath with require and ESM-compatible files. Use --import for preload and do not mix a second SDK instance into a framework bootstrap.

Node.js compatibility

Use Node.js 20 or newer. The SDK registers OpenTelemetry’s asynchronous loader hook with node:module.register(); newer Node.js deprecations do not change the documented startup command.