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

# Troubleshooting

> Common Auth0 Relationship Sync failure modes, including FGA drifting from Auth0, and how to resolve them, plus mapping and rate limits.

## FGA doesn't match Auth0

A tuple is missing, stale, or unexpected even though the Sync pipeline is running and healthy.

The Sync pipeline applies every event it consumes, so first check the **Logs** section to see whether the relevant event arrived and was processed. If it never arrived, Auth0 didn't emit it: Auth0 doesn't guarantee that every change produces an event, or that events are delivered in order when changes race. See [Event delivery and consistency](https://docs.fga.dev/relationship-sync/overview.md#event-delivery-and-consistency).

**Fix:** reconcile the affected objects against the Auth0 Management API; see [Backfilling and reconciling](https://docs.fga.dev/relationship-sync/managing.md#reconciling). If the event did arrive and the tuple is still wrong, check your mapping rule with `fga mapping run`.

## Stuck in Pending Verification

The Sync pipeline was created but hasn't finished verification yet: it's missing a model and mapping, working credentials, or both.

This is expected right after finishing the setup wizard: the wizard only configures and verifies authentication, so a newly created Sync pipeline has no model or mapping selected yet and sits in this state until you add one from its **Add Mappings to Pipeline** page. You'll also see this status if your credentials themselves haven't verified; see [Auth0 authentication is failing](#auth0-authentication-is-failing) below.

**Fix:** go to the Sync pipeline's **Mappings** tab and add a model and mapping; see [Add a model and mapping](https://docs.fga.dev/relationship-sync/getting-started.md#add-a-model-and-mapping).

## Key validation failed at setup

During the setup wizard's **Establish Private Key JWT Connection to Auth0 Application** step, clicking **Verify Connection** fails with **Key validation failed**. This means Auth0 didn't accept the public key as a valid Private Key JWT credential on the Machine-to-Machine application, usually because the upload didn't complete, the wrong file was uploaded, or the credential wasn't saved on the Auth0 side.

**Fix:** download the key again from the wizard and re-upload it to your Machine-to-Machine application's Private Key JWT credential in Auth0, then click **Verify Connection** again.

## Auth0 authentication is failing

Auth0 is rejecting authentication. This usually means the public key was removed or replaced in your Auth0 application, its Auth0-side expiration has passed (if you set one, under **Never**, **From certificate**, or a **Custom date** on the credential), or there's a mismatch between what FGA is signing with and what Auth0 has on file. FGA itself imposes no expiration on the key; see [Rotating credentials](https://docs.fga.dev/relationship-sync/managing.md#rotating-credentials).

You do **not** need to recreate the Sync pipeline from scratch for this; that's only necessary if the Machine-to-Machine application itself was deleted in Auth0, or if you need to change the domain or Client ID (those can't be edited on an existing Sync pipeline).

**Fix:** in the Auth0 Dashboard, confirm the correct public key is registered under your Machine-to-Machine application's Private Key JWT credentials and that its configured expiration (if any) hasn't passed, re-add it if needed, then click **Resume**.

## Can't resume or activate from that far back

Starting a Sync pipeline, or resuming a paused one, from an explicit point in time is capped at **7 days** back. Requesting an earlier timestamp is rejected, and the Sync pipeline is not started or resumed.

**Fix:** pick a timestamp within the last 7 days, or omit it to start/resume from the default position (the current time for a new pipeline, the last processed cursor for resume). If you need data from further back than 7 days, backfill it separately; see [Reconciling](https://docs.fga.dev/relationship-sync/managing.md#reconciling).

## A second Sync pipeline for the same tenant doesn't sync events

Auth0 limits how many concurrent connections a tenant's Events API can have open at once, and that limit depends on your Auth0 plan; see the **Event Streams** row under **Extensibility** on the [Auth0 pricing page](https://auth0.com/pricing). If you exceed it, for example by creating a second Sync pipeline against a tenant that already has one active, or by running some other tool that also consumes that tenant's Events API, the new connection is rejected and the Sync pipeline moves to `PAUSED_CONNECTION_LIMIT`.

**Fix:** free up a connection within your tenant's Event Streams limit, by pausing or deleting whichever other Sync pipeline (or other Events API consumer) is already connected to that tenant, then click **Resume**.

## Stuck on a poison event

A specific event failed processing repeatedly (5 times by default). Common causes are a malformed event payload or a bug in your mapping, for example a type transformation that doesn't hold for every event of that type. By design, the worker does not skip the event or move past it: consistency is prioritized over staying available.

**Fix:**

1. Check the **Logs** section in the sidebar for details on the failing event.
2. If the cause is in your mapping, fix it and [update the mapping](https://docs.fga.dev/relationship-sync/managing.md#change-the-model-or-mapping).
3. Click **Resume**.

## Paused by the circuit breaker

This Sync pipeline's error rate crossed a threshold (for example, more than 10% of events failing). FGA runs many Sync pipelines on shared underlying workers, so this protects others from being affected by a bug specific to yours.

**Fix:** check the **Logs** section for the underlying errors, fix the cause, then click **Resume**.

## Mapping validation errors

Validation errors appear in the dashboard when you click **Add Mappings** (or **Update Mappings**) on the Sync pipeline's **Mappings** tab, or locally when you run `fga mapping validate mapping.yaml --model-file model.fga`. Both surface the same three categories.

The CLI reports its result via exit code, useful for scripting or CI: `0` on success, `1` for a runtime failure (I/O, JSON parse/eval error, or a failing test if you also ran `fga mapping test`), `2` for a usage error, compile error, or model inconsistency. See [Working with Mapping Files](https://docs.fga.dev/relationship-sync/mapping-files.md#using-the-cli) for the full CLI reference.

### Invalid YAML

The file could not be parsed. The error message includes the line and column where parsing failed. Fix the syntax and re-run; no further validation runs until the file is valid YAML.

### Structural errors

The YAML is valid but the mapping itself is malformed. Each error reports a field path and line/column position; all errors across all rules are reported at once rather than stopping at the first one.

Common causes:

* **Missing required fields** — `name`; `tuples` (or `iterator.tuples`), unless `tuple_filters` is present with every filter's `action` set to `delete`; `as` on an iterator; `source` on an iterator.
* **Invalid action values** — tuple and filter actions have distinct valid sets: tuples accept `write` (default) or `delete`; tuple filters accept `delete`, or omit `action` entirely to reconcile against `tuples`.
* **Contradictory filter and action combinations** — for example, a rule with all-delete filters cannot also define desired-state tuples, and a reconciling filter (no `action`) cannot coexist with a `delete` action at the rule or tuple level.
* **Variable errors** — duplicate variable names, a variable expression that references another variable defined later in the list, or a rule-level `when` guard that references `variables.*` (variables are not in scope when the guard is evaluated).
* **Iterator `as` name collision** — `input` and `variables` are reserved names and cannot be used as the iterator alias.

### Model consistency errors

The mapping is structurally valid but references types, relations, conditions, or context keys that do not exist in the selected FGA model. This is checked automatically against whichever model is selected on the Sync pipeline when you validate.

Common causes:

* A tuple template writes to a relation that does not exist on the declared object type.
* A user type in a tuple template is not a valid assignee for that relation.
* A `condition` name or `context` key does not exist in the model.

All rules are checked before errors are returned, so you see the full list in one pass. See [Validating a mapping file](https://docs.fga.dev/relationship-sync/mapping-files.md#validating-a-mapping-file) for the full validation flow.

## Limits

| Limit | Value |
| - | - |
| Max rules per mapping file | 100 |
| Max tuples per event | 40 |
| Max iterator items per rule | 1000 |
| Max variable value size | 4 KB |
| Evaluation timeout per event | 20 ms |
| Max candidate keys at once | 1 |