> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fleack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Fleack: error codes and common issues

> Every error Fleack returns, what it means for your app or team, and the exact steps to resolve it — including health check endpoints.

Fleack returns named, structured error codes so you can diagnose problems quickly without guessing. This page covers every error you can encounter — whether it surfaces in your mobile app, in the backoffice, during test setup, or in the lever wizard — and walks you through the fix for each one.

## Edge errors

These are the only Fleack errors that **reach your mobile app**. All other errors are contained to the backoffice or your internal tooling.

<AccordionGroup>
  <Accordion title="404 tenant_not_found">
    ```json theme={null}
    { "error": "tenant_not_found", "host": "<the host that was sent>" }
    ```

    The hostname your app sent in the `Host` header didn't match any tenant configured in Fleack. Fleack couldn't identify which tenant should handle the request.

    <Steps>
      <Step title="Verify DNS is pointing at Fleack">
        Check that your API subdomain resolves to a Fleack address. Run a DNS lookup for your hostname and confirm the result is the Fleack address you were given during setup.
      </Step>

      <Step title="Confirm the tenant route exists">
        Open the backoffice and go to **Admin → Tenants**. The `host` field on your tenant must match exactly what your app sends in the `Host` header — including subdomain.
      </Step>

      <Step title="Wait for the cache to refresh">
        If you recently added or updated the tenant, the gateway can take up to 10 seconds to pick up the change. Wait briefly, then retry.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="502 origin_unreachable / tenant_unreachable">
    ```json theme={null}
    { "error": "origin_unreachable", "target": "<upstream URL>", "message": "..." }
    ```

    Fleack successfully received your app's request but couldn't reach your real backend to forward it. The `message` field contains the underlying network error (for example `ECONNREFUSED`, `ENOTFOUND`, or `ETIMEDOUT`).

    <Warning>
      This is a **fail-open** scenario. From your app's perspective it looks the same as if your backend had gone down without Fleack in the path. Your existing retry and offline-mode logic handles it normally — Fleack never introduces new failure modes.
    </Warning>

    <Steps>
      <Step title="Check your backend is reachable">
        Verify your real backend is up and responding. Try hitting your backend's health endpoint directly from outside Fleack to confirm it's available.
      </Step>

      <Step title="Check the upstream URL in your tenant settings">
        Open **Admin → Tenants** in the backoffice and review the `upstream` field. It must be the full URL of your real backend, including protocol and any path prefix.
      </Step>

      <Step title="Check IP allowlisting">
        If your backend restricts inbound traffic by IP, ensure Fleack's egress IPs are on your allowlist. Contact [contact@fleack.io](mailto:contact@fleack.io) for the current egress IP ranges.
      </Step>

      <Step title="Read the message field">
        The `message` value tells you exactly what failed at the network level. Start your investigation on the backend side based on that error.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Backoffice errors

These errors appear in the Fleack backoffice UI or in API responses when your team manages tenants, members, and tests.

<AccordionGroup>
  <Accordion title="401 unauthorized">
    Your session has expired or wasn't included in the request.

    **Fix:** sign back in. If you keep getting `401` immediately after logging in, email [contact@fleack.io](mailto:contact@fleack.io) — this is typically a session configuration issue on Fleack's side that your account operator can resolve.
  </Accordion>

  <Accordion title="403 csrf_invalid">
    A write operation (POST, PUT, PATCH, or DELETE) was sent without a valid CSRF token.

    **Fix:** the backoffice attaches the required `x-fleack-csrf` header automatically. If you see this error, your browser session is out of sync — refresh the page and try again.
  </Accordion>

  <Accordion title="403 forbidden — super-admin only">
    You attempted to access an admin-only endpoint without super-admin privileges.

    **Fix:** super-admin is a single role granted during account provisioning. You cannot escalate to super-admin from the UI by design. If you need this level of access, contact [contact@fleack.io](mailto:contact@fleack.io) or the person who provisioned your Fleack account.
  </Accordion>

  <Accordion title="409 already_member / already_invited">
    You tried to invite someone who is already a member of the organisation or already has a pending invitation waiting.

    <Steps>
      <Step title="Check the Members page">
        Open **Members** in the backoffice. If the person is already listed, no further action is needed.
      </Step>

      <Step title="Clear a stuck invitation">
        If they have a pending invitation they haven't accepted, go to the **Invitations** tab, revoke the existing one, then send a fresh invite.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="410 invitation_expired">
    The invitation link is older than its validity window: 7 days for standard invitations, 14 days for owner invitations.

    **Fix:** ask an admin or owner to issue a new invitation from the **Members** page.
  </Accordion>
</AccordionGroup>

## Test issues

These aren't error codes — they're situations where a test appears to be running but something about the data doesn't look right.

<AccordionGroup>
  <Accordion title="Test created but no exposures arriving">
    The most common cause is a mismatch between the `endpoint_signature` the test is bound to and the signature of the requests your app is actually making.

    <Steps>
      <Step title="Check the endpoint signature on the test">
        Open the test detail page and note the `endpoint_signature` it's bound to.
      </Step>

      <Step title="Find that signature in the Endpoints catalog">
        Go to **Endpoints** in the backoffice and look for that exact signature. If it's not listed, your app hasn't hit that path recently enough for Fleack to have seen it.
      </Step>

      <Step title="Look for similar signatures">
        If you see signatures that look similar but have different query parameters, you may have created the test against an older signature. Recent versions of Fleack strip filter, sort, and pagination query keys from signatures — but a test created before that change stays bound to the old signature. Recreate the test against the current signature.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Test running but the lever still shows the control value">
    This is expected and correct behaviour. The **Levers** catalog shows the value your backend actually returns — a snapshot taken before any variant injection. Fleack is still injecting the variant value for users in the test group.

    <Tip>
      To verify injection is working, make a request directly to your tenant URL with a matching `User-Agent` header from a clean IP. Check the response body — you should see the variant value if that user falls into the test group.
    </Tip>
  </Accordion>

  <Accordion title="exposed_users stays at 0 even though events are firing">
    There are two distinct causes:

    **Anonymous traffic.** The `exposed_users` counter only increments for exposures with a non-null user identity — a user-id header, an authenticated path, or a UA + IP fallback (available in recent Fleack versions). If you're on an older Fleack version that returned `null` for anonymous users, contact [contact@fleack.io](mailto:contact@fleack.io) to arrange an upgrade.

    **The target path is missing in some responses.** Variant injection only fires — and an exposure is only logged — when Fleack can find the `target_key` in the response body. If your backend returns different response shapes for some requests and the targeted path is absent in those responses, those requests won't produce an exposure. Check the test's `target_key` against your actual response body to confirm the path always exists.
  </Accordion>
</AccordionGroup>

## Lever wizard issues

<AccordionGroup>
  <Accordion title="&#x22;No endpoint captured yet&#x22;">
    The wizard found no endpoints with captured body samples. This means either no traffic has passed through your tenant yet, or all requests so far returned non-JSON content (HTML, binary, etc.).

    **Fix:** exercise your app so that real traffic flows through the Fleack tenant, then refresh the wizard. Any JSON-returning endpoint will appear once Fleack has seen at least one response from it.
  </Accordion>

  <Accordion title="&#x22;No scalar value found in the captured body&#x22;">
    The endpoint's most recently captured response had no leaf scalar values that Fleack could surface as a lever. This is common when the response is a list of objects (`[{...}, {...}]`) without nested scalars, or when the response body is empty.

    <Steps>
      <Step title="Confirm the endpoint returns the value you want to test">
        Check your backend — make sure the parameter you want to experiment on (for example `data.config.gems_reward`) is actually present in the response body.
      </Step>

      <Step title="Inspect the captured sample in the backoffice">
        Open the endpoint in the backoffice and review its captured sample. You'll be able to see exactly what body Fleack last recorded.
      </Step>

      <Step title="Contact support if the value is there but not surfaced">
        If the scalar exists in the captured body but the wizard still doesn't show it, email [contact@fleack.io](mailto:contact@fleack.io) with the endpoint signature and the response body. We'll fix the scalar walker.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Health check endpoints

Each Fleack service exposes a health endpoint you can poll for liveness probes or quick diagnostics.

| Service        | Endpoint             | What it shows                                             |
| -------------- | -------------------- | --------------------------------------------------------- |
| Gateway        | `GET /_flick/health` | `tenants_count` and the current tenant host registry      |
| Tenant service | `GET /_flick/health` | `events_count`, `active_tests`, and database connectivity |
| Control-plane  | `GET /health`        | Database connectivity and AI integration status           |

<Note>
  If a tenant's health endpoint shows `active_tests: 0` despite a running test in the backoffice, the cache hasn't refreshed yet. Wait 5–10 seconds and check again. If it stays at `0` after 30 seconds, contact [contact@fleack.io](mailto:contact@fleack.io) with your `tenant_id`.
</Note>

## Still stuck?

Email [contact@fleack.io](mailto:contact@fleack.io) with:

* The error code or a description of the symptom (a screenshot helps)
* The relevant `endpoint_signature` and `tenant_id`
* The approximate timestamp so we can locate the event in logs

We respond within one business day.