---
url: https://game-engine-io.github.io/enginex-frontend-sdk/guide/troubleshooting.md
---
# 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](/concepts/errors) and
[Error codes](/concepts/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](/guide/installation#local-development) and
[Tenant and domains](/concepts/tenant).

```ts
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](/guide/installation#gateway-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](/guide/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 `baseUrl` **and** `tenantHost`.
* **No `fetch`** in the environment: pass `fetch` in 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](/concepts/tenant#server).

## 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
  `localStorageTokenStore` falls back to memory and the session dies on reload. Detect it with
  `enginex.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 same `key` (default `getenginex.tokens`).
* **Different origins:** `localStorage` is 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 `onSessionExpired` is
  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](/concepts/session).

## Device clock

**Symptom:** a refresh on every request or several `401`s 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.
