Common problems

setup fails because users already exist#

kiwi flow setup is a one-time bootstrap and fails if any user exists. Sign in with an existing admin instead, then create users with user-add and keys with key-add.

A workflow will not load: "Cycle detected"#

Message: Cycle detected: [a2 → a3 → a2]. Loopback connections require a branching condition (if_else or switch) in the cycle.

Cause: A back-edge forms a cycle with no if_else or switch to provide an exit.

Fix: Put a branching activity inside the loop, or use foreach or repeat_while instead. Run workflow-validate to see all errors at once.

A run stops: an activity "has been executed N times"#

Cause: The run-time guard stopped an activity that exceeded maxLoopIterations (default 1000), usually because an exit condition never became true.

Fix: Correct the condition. For a loop that is expected to be short, lower maxLoopIterations on the workflow so a mistake is caught early.

InputResolutionException#

Cause: A required input has no value. The engine tried an explicit mapping, auto-promotion from the direct predecessor, a global with the same name, a workflow input with the same name, and then the default.

Fix: Map the input explicitly with from, value or expression. Remember that auto-promotion is disabled at merge points. Check spelling of the path, for example a1.output.token.

A deep path returns nothing#

a1.output.body.UserEmail resolves by looking for the literal key first and then drilling into nested JSON. Check that the activity really returns a nested body (log or inspect the run with kiwi flow run-get --id <run-id>), and that the property name's case matches.

Validation reports unknown activity type or dangling reference#

Activity types are exact strings such as http_request (see the catalogue). Every next, branch next, switch default and onError.activityId must point at an activity id that exists, including ids inside parallel branches and loop bodies. Activity ids must be unique across the whole workflow.

An AI-generated workflow has blank values#

This is expected. URLs, connection details and other mandatory values are left as placeholders for you to fill in after generation. Review the workflow, fill them in and re-validate.

AI generation is unavailable#

AI generation is a separately licensed capability and needs a configured AI assistant. Check kiwi flow license-status and kiwi flow ai-assistants, and test the provider with ai-assistant-test.

A run is rejected or cut short#

A run-level resource guard fired: the run timeout, the per-activity maximum output size or the concurrent-run limit. Review the values with kiwi flow resource-guards-get, and reduce the work (for example page large results) or ask a superadmin to adjust them.

A Kiwi Fabric or Kiwi Distro activity is refused#

The connectors are individually licensed (Connector:kiwi_fabric, Connector:kiwi_distro). Confirm the entitlement with kiwi flow license-status, then verify the connection fields with kiwi flow connection-test.

A remote script times out#

kiwi_distro_script waits up to pollTimeoutSeconds (default 900). Raise it for long scripts, and check in Kiwi Distro that a worker with the right executor and tags is registered. See the Kiwi Distro troubleshooting guide.