Docs
Kiwi Fabric
Version Current

Troubleshooting

Common problems

Setup, authentication, query-limit and saga failures, with their causes and fixes.

Fabric Current 3 min read Updated

auth-setup fails because users already exist#

Symptom: kiwi fabric auth-setup, or POST /api/auth/setup, returns an error (409).

Cause: First-time setup is allowed only when no user exists. This is deliberate so it can never be used to take over a configured instance.

Fix: Sign in with an existing admin (kiwi fabric login), then create users with user-add and keys with key-add.

I lost the API key#

Cause: The raw key is displayed once; only a hash is stored.

Fix: Create a new key (key-add) and revoke the old one (key-revoke).

401 from REST or Arrow Flight#

Check:

  • REST accepts Authorization: Bearer <key>, X-Api-Key, or Basic auth.
  • Arrow Flight needs the same Authorization value in gRPC metadata.
  • The key may have expired or been revoked (kiwi fabric keys).
  • The user may be deactivated (user-activate).

A PostgreSQL client cannot authenticate#

The wire protocol uses SCRAM-SHA-256. Use a client or driver version that supports it, and the user name and password of a Kiwi Fabric user (not an API key).

A query is rejected or cancelled#

Cause: A resource guard fired: the query timeout, the maximum result rows (checked per handler fetch and again on the final result), or the concurrency cap.

Fix: Narrow the query with filters or OFFSET/FETCH, or have a superadmin raise the limit with resource-guards-set. Telemetry records which guard fired. See Configure resource guards.

A cross-source query is slow#

  • Run it with --verbose and check the per-source breakdown for sources that return many rows.
  • A source with no predicate pushdown returns more data, but still correct results. Review the capability's predicate setting.
  • For joins that filter one source by another, tune the per-provider semi-join settings, and check the fallback policy (abort or unfiltered fetch). See Performance and resource limits.

A saga failed#

  1. Inspect it: kiwi fabric saga-status --id <id>.
  2. Look at the step table for the failing step and its error message.
  3. Confirm compensation ran for earlier steps (their compensated flag), and check saga-gaps for any step that could not be undone.

Common causes of a failing step are database errors from the target system, such as a duplicate key or a value too long for its column. Fix the payload and re-run; use idempotency keys to make retries safe.

$ref does not resolve#

A { "$ref": "stepId.keyName" } needs the referenced step to be listed in dependsOn, and keyName to match the generated column's logical name. A table with no identity column declared on its capability returns generated keys under a fallback name, and insert compensation then cannot delete the right row. Declare the identity column on the capability.

Rollback reports a gap#

This means a write path has no automatic compensation (for example raw SQL without compensation SQL, or a REST call without a compensation URL). Add compensation, or accept and document the risk. See Sagas and compensation.

A change to the registry did not take effect#

Direct edits to registry data may not rebuild the live engine. Make configuration changes through the Web UI, CLI or REST API, which apply them correctly, and restart the service if you edited the registry by other means.