Verification and common problems - Next.js

A controlled test event

import { getRay } from '@dockcodes/dock-ray-next';

await getRay().captureMessage('DockRay control message');

Call this from a temporary route on a staging environment and remove it right after the test succeeds - further calls eat into the monthly error quota. The message should appear in the panel under Errors for the project the token points at, with the environment name preserved.

Common problems

The private key ended up in browser code

If RAY_PRIVATE_KEY got a NEXT_PUBLIC_ prefix, Next inlined it into the client bundle on the first build - which means the key is already public. Renaming the variable does not undo the leak: revoke the key in the panel and generate a new one.

Middleware errors are not reported

Middleware is always an edge bundle. Importing from the main entry point (@dockcodes/dock-ray-next) instead of /edge, or missing withRayMiddleware around the middleware function, is the most common cause.

A report from the edge does not arrive despite a correct setup

An edge invocation can be frozen the moment the function returns a value. The edge wrapper awaits its report specifically for that reason - make sure the error actually travels through withRayMiddleware or rayRequestError from /edge, not through your own unfinished ray.report() call.

JavaScript errors from the browser do not arrive

The route always answers 202, whether or not it accepted the report - that is intentional, so a caller learns nothing about the guards. Check separately: whether NEXT_PUBLIC_RAY_JS_ERRORS=true is set (a change needs a rebuild, because it is baked into the bundle at build time), whether RayBrowserReporting is mounted in the root layout, whether app/api/ray/browser/route.ts has export const runtime = 'nodejs', and - the easiest thing to miss - whether the server even has RAY_TOKEN and RAY_PRIVATE_KEY set. Without them the route still answers 202, it just forwards nothing.

Transactions are missing

RAY_TRACES_SAMPLE_RATE defaults to 0. The token and key alone do not switch tracing on.

A Vercel preview deployment reports as production

VERCEL_ENV and VERCEL_GIT_COMMIT_SHA are only used when RAY_ENVIRONMENT and RAY_RELEASE are unset. If the Vercel project settings define RAY_ENVIRONMENT=production for every environment at once, automatic detection stops working and every preview reports as production.

One error splits into many entries

The panel groups by the fingerprint sha256(project token + type + message). Next adds tags from the route context, but that does not change the type or the message - an identifier pasted into the exception message still splits one error into a thousand rows.

The panel answers 200 but there is no event

A 200 {"success": false} response means the account has used up its monthly error quota. The integration does not treat that as a failure - and rightly so. You can see the quota on the account dashboard; until the end of the month it is counted from recorded usage, so deleting errors does not reset it.

Still not working

Work through the troubleshooting checklist, and if that does not help, write to us. Include the project name, the integration version and roughly when you ran the test: it shortens the way to an answer.