Common Issues & Fixes
A diagnostic runbook covering the most frequently encountered configuration errors, credential mismatches, and offline compilation warnings.
“Before digging into stack traces, run the CLI doctor command to automatically detect missing env variables, outdated packages, and lockfile corruptions.”
Error: “Missing Project ID”
Symptom: The React SDK throws an error on boot, or content fetching requests fail instantly.
Diagnosis: The GN-Apex singleton cannot locate your project context in the environment variables. Next.js aggressively strips variables from the browser bundle unless they are prefixed properly.
Prefix with NEXT_PUBLIC_
Ensure your .env.local file uses NEXT_PUBLIC_NEXUS_ID, not just NEXUS_ID.
| 1 | # Verify the variable is actually injected into the Node process |
| 2 | echo $NEXT_PUBLIC_NEXUS_ID |
| 3 | |
| 4 | # If empty, restart your Next.js dev server to flush the env cache |
| 5 | npm run dev |
CORS Rejection (HTTP 403 Forbidden)
Symptom: Browser console shows Cross-Origin Resource Sharing errors when calling /api/collect or fetching content.
Diagnosis: Your frontend is attempting to query the API using a Public Key (nx_pk_live_), but the domain it is making the request from (e.g. https://staging.mybrand.com) is not whitelisted in the Control Plane.
Fix: Log into the dashboard, navigate to Settings → API Keys, and ensure your staging/production domain is added to the Authorized Origins list. (Note: localhost is automatically whitelisted during development).
Data Integrity Violation (Binary Mismatch)
Diagnosis: You attempted to start the offline studio (npx nexus studio), but one of your .nx binary files failed its constant-time HMAC signature verification. This usually happens if you attempt to resolve a Git merge conflict directly inside a .nx file.
Fix: Delete the corrupted binary and re-sync from the upstream remote:
| 1 | # Hard reset the local directory |
| 2 | rm -rf .nexus/local |
| 3 | |
| 4 | # Re-download secure binaries from the edge |
| 5 | npx nexus pull --force |
WebPush Notification Failures
Symptom: <NexusProvider autoPromptPush={true}> does not show a browser notification prompt, or the subscription fails.
- HTTPS Requirement: The browser PushManager API strictly requires a secure context. Ensure your staging environment is served over HTTPS (localhost is exempt).
- Service Worker Path: Ensure
/sw.jswas correctly generated in your/publicdirectory duringnpx nexus init. - Browser Blocks:Check if the user previously clicked “Block” on the site settings. The prompt will not reappear automatically.