Troubleshooting

Startup. Look for the Vigilon started: line in your app's output. It shows the service name, environment, and version Vigilon is using, and where each one came from.

Requests. Make a few requests to a normal route, then open the matching project in Vigilon. Data should appear within 30-45 seconds. Health checks are left out by default, so calling /health will not verify the setup.

Errors. Call a route that uses recordException, like the example in Recording errors, and look for the error in Errors.

Jobs. Run a job wrapped with withJobMonitor and look for its name in Jobs.

Start with the Vigilon started: line. If it is missing, your app was not started with the --import flag, or VIGILON_DISABLED is set. If a required setting is missing, the app stops at startup instead, and the message names the variable to set.

Next, confirm you are looking at the right project. An API key belongs to one project, and data sent with it always goes to that project. A key copied from another project works without any error, but the data shows up there.

Then look for one of these messages in your app's output:

Vigilon: the ingest endpoint rejected the API key (HTTP 401). Traces are not being delivered. Check VIGILON_API_KEY.

Vigilon: exporting traces failed: <reason>. Set VIGILON_DEBUG=1 for OpenTelemetry diagnostics.

HTTP 401 in the first message means the API key is not valid or was revoked. Create a new key in your project's settings and update VIGILON_API_KEY.

HTTP 403 in the first message means the key is fine, but Vigilon is not accepting the data: your workspace has used its monthly quota, or the app is sending faster than the rate limit allows. Check your usage in the dashboard.

The second message points to a network problem or a wrong VIGILON_OTEL_ENDPOINT. Each message is printed only once.

For more detail, turn on debug logging and restart the app:

export VIGILON_DEBUG=1

Also confirm that the variables are set in the process that runs your app, not only in your own shell. Vigilon cannot see a .env file that your code loads with dotenv; start Node with --env-file=.env instead.

The Vigilon started: line shows where each value came from. The usual causes are a script at the root of a monorepo that starts an app in another package, which reports the root package's name, or NODE_ENV=production on a staging server. Set VIGILON_SERVICE_NAME or VIGILON_ENVIRONMENT. They always win.

If requests appear without a route, as GET instead of GET /users/:id, or database queries are missing, Vigilon started after those libraries were loaded. Check these in order:

Start flag. An ES module app must use --import. --require only works for CommonJS apps.

Starting from code. Importing @vigilon/node/register or calling register() inside your app is too late for ES modules. In CommonJS it must come before every other require. See the Configuration guide.

Bundlers. esbuild and similar tools copy libraries into one file, which stops Vigilon from hooking into them. Keep @vigilon/node and @opentelemetry/* external, as described in the AWS Lambda guide.

Jobs. Installing BullMQ or a scheduler is not enough. Each job has to be wrapped with withJobMonitor. If the job is a script that exits when it finishes, await shutdown() before exiting, as shown in the Background jobs guide.

Errors. Errors you catch yourself are only recorded if you call recordException(error) inside a request, job, or Lambda invocation.

Vigilon is already registered. Vigilon was started twice, usually by the --import flag and a register() call. Keep one.

Vigilon could not determine a service version. Your app still works. Set VIGILON_SERVICE_VERSION or add a version to package.json to track deployments.

--import fails with an error that mentions module.register or node:module. The flag needs Node.js 20.6 or later.