Troubleshooting
Find out why expected requests, errors, or jobs are not appearing in Vigilon.
Check each kind of data
Startup. Look for the Vigilon started: line in your app's output. It shows the app 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.
Nothing arrives
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. An API key still set to a placeholder in square brackets, as in the samples in these guides, counts as missing.
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 Vigilon is not accepting the data, and the SDK does not retry. Either the key is not a Server key (check its kind on the project's API Keys tab; the SDK needs a Server key), or your workspace's free trial ended without a card and it is paused until an owner starts a subscription in billing settings.
A workspace that has reached a plan quota, or an app sending faster than the rate limit allows, is answered with HTTP 429 instead. The SDK retries those, and reports what it could not deliver with the second message. 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 app name or environment is wrong
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_APP_NAME or VIGILON_ENVIRONMENT. They always win.
Routes or database queries are missing
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 or errors are missing
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.
Startup warnings and errors
Vigilon is already registered. Vigilon was started twice, usually by the --import flag and a register() call. Keep one.
Vigilon could not determine an app version. Your app still works. Set VIGILON_APP_VERSION or add a version to package.json to track deployments.
VIGILON_SERVICE_NAME is deprecated. Vigilon 0.2.24 renamed four settings: VIGILON_SERVICE_NAME is now VIGILON_APP_NAME, VIGILON_SERVICE_VERSION is now VIGILON_APP_VERSION, and the register() arguments serviceName and serviceVersion are now appName and appVersion. The old names keep working until 0.3.0. Rename them to remove the warning.
--import fails with an error that mentions module.register or node:module. The preload needs Node.js 22.12 or later.