Skip to main content

​
Symptom → Cause → Fix

SymptomMost likely causeFix
Blank div, nothing rendersOrigin not in allow-listAdd your origin in the dashboard (see Allowed Origins)
onError fires: ORIGIN_NOT_ALLOWEDSame as aboveAdd the origin
onError fires: TOKEN_INVALIDWrong or expired API keyCheck EDPIRE_API_KEY; ensure no VITE_/NEXT_PUBLIC_ prefix
onError fires: TOKEN_EXPIREDToken older than 1 hourMint a fresh token each time the learner opens the assessment
onError fires: TOKEN_USEDSame token used twiceMint a new token per page load (tokens are single-use)
onError fires: ASSESSMENT_NOT_FOUNDWrong ID or unpublishedVerify the UUID; publish the assessment in the dashboard
onError fires: MAX_ATTEMPTS_REACHEDLearner used all attemptsShow your own “no attempts left” UI; no action needed
Player loads, then cuts off / looks wrongContainer has no height or is constrainedSet an explicit height on the container div (see Container sizing)
Works in npm run dev, breaks in productionToken endpoint was dev-only (Vite middleware)Use a real server route — see Token endpoint not found in production
Token endpoint returns 401resolveLearner returned nullEnsure the user is logged in before the assessment page loads
Token endpoint returns 400Missing assessmentId in POST bodyCheck that you’re POSTing { assessmentId } to the endpoint
No onError call, no playerContainer element not foundEnsure the container id/class exists in the DOM before calling mount()
API key leaks to the browserUsed VITE_EDPIRE_API_KEY or NEXT_PUBLIC_EDPIRE_API_KEYRemove the prefix — the key must be server-side only
React StrictMode mounts twiceExpected in dev — useEffect double-invokesThis is handled automatically by <EdpireAssessmentPlayer> and the cancelled flag pattern
NETWORK_ERROR in onErrorCan’t reach edpire.comCheck connectivity; verify baseUrl if using staging

​
Allowed Origins

The embed player is scoped to domains you explicitly allow. Without this, the player returns ORIGIN_NOT_ALLOWED.
  1. Go to edpire.com → Settings → Integrations → Allowed Origins
  2. Add every origin your app runs on:
    • http://localhost:3000 (Next.js dev)
    • http://localhost:5173 (Vite dev)
    • https://yourapp.com (production)
  3. Save — changes take effect immediately (no rebuild needed)
To quickly confirm it’s an origin error, add a temporary onError log:
onError: (e) => console.error("[edpire]", e.code, e.message)

​
Token endpoint not found in production

If the player worked in npm run dev but fails in production with a 404 on /api/edpire/token, the token endpoint was probably a Vite dev-server middleware — which only runs during vite dev, not after vite build. Fix: Move the token endpoint to a real server route:
  • Next.js: app/api/edpire/token/route.ts with createEdpireTokenHandler() (works in both dev and prod)
  • Vite + SPA: Add an Express server and proxy /api to it — scaffold with npx --package=@edpire/sdk create-edpire-app vite-express my-app

​
API key exposed in browser bundle

If your API key is prefixed with VITE_ or NEXT_PUBLIC_, it compiles into the browser JavaScript. Anyone can read it. 
# Wrong
VITE_EDPIRE_API_KEY=edp_live_...      # leaks to browser
NEXT_PUBLIC_EDPIRE_API_KEY=edp_live_  # leaks to browser

# Correct
EDPIRE_API_KEY=edp_live_...           # stays on the server

​
Still stuck?