Setup

The dashboard ships with the errorcore package. It reads error packages from an NDJSON file (the same format used by the file transport and the dead-letter store) and serves a web interface.

Quick start

launch the dashboard

npx errorcore ui

This looks for errorcore.config.js in the current directory, resolves the NDJSON file path from the transport or dead-letter config, and starts the dashboard on http://localhost:4400.

CLI flags

Flag	Description	Default
`--config <path>`	Path to your errorcore config file.	`./errorcore.config.js`
`--port <number>`	Port to serve the dashboard on.	`4400`

custom config and port

npx errorcore ui --config ./config/errorcore.config.js --port 9000

File resolution

The dashboard determines which NDJSON file to read based on your config, in this order:

If the transport is type: "file", it uses that file path.
If a deadLetterPath is configured, it uses that.
Otherwise, it looks for .errorcore-dead-letters.ndjson in the current directory.

File paths in the config are resolved relative to the config file's directory, not the working directory you launched the command from.

By default, the dashboard binds to 127.0.0.1 (localhost only) and does not require authentication. If you need to expose it on a network or run it on a shared server, set an access token via the EC_DASHBOARD_TOKEN environment variable:

with authentication

EC_DASHBOARD_TOKEN=your-secret-token npx errorcore ui

When a token is set:

the server binds to 0.0.0.0 (all interfaces) instead of localhost
all API requests require the token
the browser prompts for the token on first load

Do not expose the dashboard to the public internet without a token. Error packages can contain stack traces, request context, environment variables, and other sensitive debugging information.

Encrypted packages

If your config includes an encryptionKey, the dashboard decrypts packages on the fly when reading them. No additional flags are needed. The key is read from the same config file used to launch the dashboard.

If you are viewing packages that were encrypted with a different key, update the config to use the correct key before launching.

File watching

The dashboard watches the NDJSON file for changes. When new errors are written (by a running service or by draining the dead-letter store), the dashboard re-indexes automatically. You can also trigger a manual refresh from the browser or by hitting the /api/refresh endpoint.

API endpoints

The dashboard exposes a JSON API alongside the web interface. If you need to query errors programmatically or integrate with other tools:

Method	Endpoint	Description
`GET`	`/api/errors`	Paginated error list. Accepts `page`, `limit`, `search`, `type`, and `sort` query parameters.
`GET`	`/api/errors/:id`	Full error package by ID.
`GET`	`/api/stats`	Aggregated statistics (totals, by type, by hour, top errors).
`POST`	`/api/refresh`	Force re-index of the NDJSON file. Requires `X-ErrorCore-Action: true` header.
`GET`	`/api/health`	Health check.

When a token is configured, include it as a Bearer token in the Authorization header for API requests.