Troubleshooting

Start with the doctor. Then work through the specific failure below.

First move: `flowifai doctor --strict`

flowifai doctor --strict

Doctor runs a check series and prints one line per check with a recovery hint on anything unhealthy:

Check	What it verifies
`local_version`	The installed CLI version.
`install_layout`	`~/.flowifai` home and install directory are intact.
`local_config`	`~/.flowifai/config.json` exists with the values `connect` wrote.
`broker_bind`	The configured broker listen address.
`wrapper_path`	The installed `flowifai-wrapper` binary is present.
`backend`	The backend URL answers its health endpoint.
`registration`	Your server is registered under the configured name and credential.
`broker`	The local broker answers on its URL.

With --strict, doctor exits nonzero when any check is warn/fail — useful in scripts. Add --json for machine-readable output, and --check-update to also verify the signed release channel. A green doctor does not by itself prove end-to-end approval execution; it proves install, backend, and broker health.

For setup-managed profiles, diagnose one profile or all of them:

flowifai status --profile PROFILE_ID
flowifai doctor --profile PROFILE_ID --strict
flowifai doctor --all --strict

Use flowifai broker logs --profile PROFILE_ID for that profile’s service log.

For an interrupted onboarding run, inspect the journal rather than rerunning setup blindly:

flowifai setup status
flowifai setup status RUN_ID
flowifai setup logs RUN_ID

Status without a run ID selects the latest run. It prints the durable state, exact rollback deadline, and safe next action. Use flowifai setup resume RUN_ID when status directs you to it: commit-boundary states finish activation, while authorized or enrolled interruptions reconcile enrollment as needed and perform a revoke-first safe rollback. Other earlier uncertain states are refused.

Setup logs prints a linear, sanitized timeline for the named run. Its private local JSONL file contains only run ID, lifecycle state, outcome, and time — no MCP arguments, environment values, raw client configuration, or credentials. The file is mode 0600 and rotates at 1 MiB.

Restore client configuration after setup

For 30 days after a successful setup, restore the entire run:

flowifai setup rollback RUN_ID

Rollback opens browser authorization, revokes backend profiles first, disables local profiles, restores the exact retained Cursor and Claude Code configuration, and removes the run’s broker services. If it is interrupted, fix the reported problem and run the same rollback command again. After the exact deadline shown by flowifai setup status RUN_ID, client restoration is refused.

To decommission only one profile without restoring its original direct client definition:

flowifai profiles remove PROFILE_ID

Profile removal requires browser authorization, revokes that backend profile before local changes, and preserves sibling profiles. It only removes exact matching flowifai wrapper entries. If a mapped client entry has changed, removal refuses to overwrite it; resolve the conflict and retry.

Setup discovery did not find an MCP

Run setup from the relevant project directory. Project and local scopes are resolved against the current directory.
Use flowifai setup --dry-run to see every discovered result and the reason an entry is unavailable.
Only local stdio definitions are supported. Remote HTTP, SSE, WebSocket, missing commands, dynamic inputs, and ambiguous definitions are listed but not converted.
Setup currently reads Claude Code user, project, and local scopes and Cursor user and project scopes. Other clients are independently gated and are not modified.

Dry run is safe for diagnosis: it does not execute MCP servers, open a browser, make network requests, or change files.

A setup-managed profile broker will not start

flowifai broker status --profile PROFILE_ID
flowifai broker logs --profile PROFILE_ID
flowifai doctor --profile PROFILE_ID --strict

The profile’s MCP command, arguments, working directory, and environment are frozen at setup time. Editing your shell or original client entry later does not update the profile in place. Run a new setup operation for a changed launch or credential.

Do not expose the profile’s ephemeral loopback endpoint. Its runtime identity prevents stale routing after restart; it is not hostile-caller authentication.

Pairing fails with 401

flowifai connect redeems a short-lived pairing token. The backend’s 401 response is deliberately uniform — it does not say whether the token was expired, already used, or simply wrong, so a failed redeem can never be used to probe token state. The CLI adds the recovery hint:

pairing tokens are single-use and expire after 10 minutes — mint a new connect command in the app (Agents → your agent → New connect command)

That is the whole recovery: open the app, mint a fresh connect command for the agent, and run it within 10 minutes. If pairing commands are disabled for your org, the app shows an enrollment credential and a --credential-stdin fallback command instead.

Missing or lost S2S credential

The durable broker credential is created during pairing and stored only in ~/.flowifai/config.json. If it is lost (deleted config, new machine), rotate/mint a replacement credential in the agent’s detail page and use the --credential-stdin fallback. Credentials are shown once — paste them only when the CLI prompts.

Broker will not start, or wrapper cannot reach it

Inspect startup failures: flowifai broker logs.
Same host: run flowifai broker start and point the wrapper at FLOWIFAI_BROKER_URL=http://localhost:8090 (the broker binds 127.0.0.1:8090 by default).
Split host: the wrapper-facing broker endpoints are unauthenticated by design and must never be exposed to a LAN or VPN directly. Start an SSH tunnel (or equivalent authenticated encrypted loopback tunnel) first, then point FLOWIFAI_BROKER_URL at the local tunnel endpoint.
New API keys or PATH entries for your MCP server: rerun flowifai broker install-service (it re-snapshots the shell environment), then restart the broker.

Schema drift: every call is refused

If the wrapped MCP server’s live tool schema no longer matches what was registered at enrollment, the broker fails closed and refuses all calls to it. Re-run the app-generated flowifai connect command to re-inspect and re-register, then:

flowifai broker stop && flowifai broker start

so the startup drift checks re-run. Note that argument-level policy rules referencing a changed schema are disabled until re-confirmed — review them in Policies after a re-register.

A gated call seems stuck pending

Check the console inbox: the ticket may simply be awaiting a human decision.
If it was approved, the agent must retry the same tool with the same arguments and the __approval_ref parameter set to the reference from the pending response. Supported clients do this automatically — see protocol-native approvals.
If the broker restarted while a call was pending, the stored arguments for replay are gone (they are held in memory, loss-tolerant by design); the retry will ask you to re-request, which creates a fresh ticket and a fresh approval.
Tickets that expire, are revoked, or fail during execution are terminal: re-running the action requires a new call and a new approval. That is fail-closed behavior, not a bug.

Command not found

Add ~/.flowifai/bin to PATH, or use the absolute path. GUI-launched MCP clients often do not inherit your shell PATH — print the exact config with:

flowifai client-config claude --print
flowifai wrapper-path

Install and update issues

Stale install lock: remove $FLOWIFAI_HOME/.install.lock only after confirming no install or update is running.
Unsupported platform: Linux and macOS on amd64 or arm64 are supported.
Release channel diagnostics: flowifai doctor --json --check-update verifies the signed manifest and the asset selected for your platform.

Still stuck? Contact us — include your flowifai doctor --json output (it contains no credentials).

View this page as markdown · All docs as one file