# Troubleshooting

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

## First move: `flowifai doctor --strict`

```sh
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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

```sh
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:

```sh
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](/docs/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:

```sh
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](/contact/) — include your `flowifai doctor --json` output
(it contains no credentials).