Skip to main content

​
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. Fix: reconcile the affected objects against the Auth0 Management API; see Backfilling and 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 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.

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

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