Troubleshooting
Common integration symptoms and how to fix them. Every SDK error is an EnginexError: start by looking at error.code, error.status and error.requestId (see Errors and Error codes).
Operator not identified (tenant)
Symptom: calls fail with an EnginexError with code: 'INVALID_ARGUMENT' and status: 400. The message is unknown domain (any route: the gateway does not recognize the domain sent in X-Original-Host) or operador não identificado (login, sign-up and phone verification). If the gateway cannot look up the operators, the error is UNAVAILABLE (status: 503, message service temporarily unavailable); in that case it is a gateway problem, not a problem with your configuration.
Cause: the gateway finds the operator by the site's domain (X-Original-Host). With the Vite/Next proxy in development the domain is localhost:5173, which is not registered with any operator.
Fix: provide the operator's domain with tenantHost (applies to same-origin calls, that is, through the /api proxy). See Local development and Tenant and domains.
createEnginexClient({ tenantHost: import.meta.env.VITE_ENGINEX_TENANT })If you call the gateway directly (cross-origin), the SDK does not send X-Original-Host: the operator comes from the Host, so the gateway's domain must be registered with the operator.
CORS and preflight
Symptom: NETWORK_ERROR in the browser, with status: 0; in the console, "blocked by CORS policy" or an OPTIONS (preflight) that fails.
Cause: a cross-origin call (baseUrl pointing at the gateway) without the site's origin allowed in the gateway's CORS, or with a header it does not allow.
Fix: prefer the same-origin proxy: without baseUrl, the request goes to the page's own origin and there is no CORS. If you need to call directly, ask for the site's origin to be allowed on the gateway.
HTML response instead of JSON (missing proxy)
Symptom: VALIDATION_ERROR with the message "Non-JSON response at ... Check the baseUrl and the /api proxy to the gateway."
Cause: /api/v1/... was answered by your own server (usually the SPA's index.html or a 404 page) because the proxy to the gateway does not exist or does not cover the path.
Fix: configure the /api proxy (Vite, Next.js, Nginx in Installation) and test curl -i http://localhost:5173/api/v1/config: the response must be JSON from the gateway. Also check that the baseUrl ends without /api (the SDK appends /api/v1).
CONFIGURATION_ERROR
Symptom: the first request rejects with code: 'CONFIGURATION_ERROR', without calling the network.
Causes and fixes:
- Outside the browser (SSR, scripts, tests in Node): provide an absolute
baseUrlandtenantHost. - No
fetchin the environment: passfetchin the client options. - Disposed client: after
client.dispose()every method rejects with this code; create another client.
The client does not throw on creation, so the error only shows up on the first request, with the message saying what is missing. See Tenant and domains.
Session dropping (localStorage and tabs)
Symptom: the player is logged out on reload, when opening another tab, or in incognito mode.
Check:
- Storage unavailable: in private Safari, with a full quota or blocked cookies/storage, the
localStorageTokenStorefalls back to memory and the session dies on reload. Detect it withenginex.session.get()after reloading and offer login again. - More than one client/
tokenStore: two instances with different keys do not share a session. Use one client per app and the samekey(defaultgetenginex.tokens). - Different origins:
localStorageis per origin;www.and the root domain, or different ports, have separate sessions. - Refresh rejected: if the gateway rejects the refresh, the session is cleared and
onSessionExpiredis called. In that case it is an expected logout (expired or revoked refresh token).
Across tabs of the same origin the session is synchronized by the storage event. See Session and tokens.
Device clock
Symptom: a refresh on every request or several 401s in a row, especially on devices with the wrong date and time.
Cause: the SDK decides to renew the access token by comparing the JWT's exp with the local clock. A clock that is ahead makes the token always look about to expire; one that is behind makes the SDK use a token that has already expired, and renewal only happens after the 401.
Fix: ask the player to enable automatic date and time. The SDK recovers on its own (reactive refresh after the 401), so the effect is just one extra request.