Troubleshooting

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 below.

Fix: go to the Sync pipeline's Mappings tab and add a model and mapping; see 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.

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.

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. 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.

This doesn't currently set a distinct paused status: the affected Sync pipeline can continue to show as Active while it fails to receive any events.

Fix: stay within your tenant's Event Streams limit. Pause or delete whichever other Sync pipeline (or other Events API consumer) is already connected to that tenant before starting a new one.

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.
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 Writing a Mapping File 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 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