Get your first errorcore event

This is the five-minute path. It mirrors the Setup page in the console, step for step.

Before you start

You need a Node.js backend and an errorcore organization. Setup issues everything else. Node.js 20 or newer is recommended.

1. Provision your organization and create a project

Open Setup in the console. If the organization has no account yet, provisioning starts its one-time Free evaluation under the live catalog policy. Provisioning is idempotent, so refreshing or retrying never creates a second account or restarts the evaluation.

Then create your first project: a lowercase project id such as core-api, a display name, and an environment (production by default). The project id appears on every admission and case.

2. Issue your server-side credentials

Setup issues two secrets in one governed step and shows each plaintext exactly once:

• ERRORCORE_API_KEY: an ec_live_ bearer credential that authenticates your servers to the ingest API.
• ERRORCORE_DEK: a 64-character hex key your process uses to encrypt the payload before it is sent.

Copy both into your server-side secret store and acknowledge the one-time display. Neither value is stored in plaintext and neither can be shown again. Details in API keys and encryption keys.

3. Install the SDK

npm install errorcore

Working with a coding agent? One prompt in Setup with an AI agent runs this page end to end in a single pass.

4. Add environment variables

ERRORCORE_API_KEY="ec_live_..."
ERRORCORE_DEK="<64-hex payload encryption key>"
ERRORCORE_ENVIRONMENT="production"
ERRORCORE_RELEASE="<full-git-commit-sha>"
ERRORCORE_INGEST_URL="https://api-production-7ecf.up.railway.app/v1/ingest"

Both keys are server-side only. Never put them in browser code, and never use a public prefix such as NEXT_PUBLIC_ on any errorcore variable.

5. Initialize errorcore

Initialize early in the server lifecycle, before database clients, HTTP clients, or job workers are created.

import { init } from "errorcore";

init({
  service: "core-api",
  deploymentEnv: process.env.ERRORCORE_ENVIRONMENT,
  transport: {
    type: "http",
    url: process.env.ERRORCORE_INGEST_URL ?? "https://api-production-7ecf.up.railway.app/v1/ingest",
    apiKey: process.env.ERRORCORE_API_KEY,
  },
  encryptionKey: process.env.ERRORCORE_DEK,
});

transport.apiKey falls back to ERRORCORE_API_KEY and encryptionKey falls back to ERRORCORE_DEK, so both lines are optional when those variables are set. They are written out here to keep the configuration explicit.

Then attach request context through your framework's adapter; see the framework guides.

6. Trigger a test error

Add the temporary server-side route shown for your framework. It explicitly calls captureError(), awaits flush(), and returns HTTP 202 so the first event is delivered before the command finishes.

The command targets your application, not errorcore. For an application running on your machine:

curl --request GET --url "http://localhost:3000/errorcore-test"

For a public deployment, replace the origin with the application's real HTTPS origin. For a private deployment, run the command inside the service or its private network and use the internal origin. The errorcore console never requests this route; it only watches the ingest pipeline for the SDK event.

The route creates real events and consumes allowance. Keep it private when possible and remove or disable it after verification.

7. Watch it arrive

The Setup page listens for your first event and follows it live through admitted, stored, reconstructing, and indexed. When indexing completes it links straight into the case.

If the event is rejected, the reason and its fix appear inline. A rejection is never softened: see troubleshooting for each reason.

What to do next

Review security and PII, understand billing and usage, then run the production checklist.