> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# fleet-rlm troubleshooting

> Fixes for common fleet-rlm issues: policy selection, Daytona credentials, database preflight failures, SSE stream errors, and MLflow tracing.

## Installation

### `No module named 'fleet_rlm'`

Sync the workspace with all extras:

```bash theme={null}
uv sync --all-extras --dev
```

Verify the entrypoints:

```bash theme={null}
uv run fleet --help
uv run fleet-rlm --help
```

### Python version mismatch

fleet-rlm targets **Python 3.13**. Install a matching interpreter through uv if needed:

```bash theme={null}
uv python install 3.13
```

## Policy and profile

### `default_profile` not set

Fleet refuses to start without an explicit `[config] default_profile` in `config/fleet.toml`. Pick one of the shipped profiles:

```toml theme={null}
[config]
default_profile = "daytona-recursive"
```

The pi-tui `/profiles` command edits this key interactively for the next restart.

### `fleet cli` rejects a non-daytona profile

`fleet cli` accepts only profiles whose runtime environment is `daytona`. Selecting a different environment fails before database preflight, MLflow startup, or backend spawning. Switch to a Daytona profile or use `fleet-rlm serve-api` for backend-only setups.

### Unknown TOML key error at startup

Fleet fails startup on unknown keys, missing profiles, invalid variable references, and absent TOML. Common culprits:

* `mlflow.trace_content_mode` — removed. Delete the key.
* `rlm.recursion_max_depth` — removed. The native child boundary is a fixed invariant. Delete the key.

## Configuration

### `Daytona configuration missing`

Every profile requires `FLEET_DAYTONA_API_KEY`. Set it in `.env` or export it:

```bash theme={null}
export FLEET_DAYTONA_API_KEY=your-daytona-api-key
```

### Provider credentials missing

Only the environment variables named by the selected profile are read. For `daytona` and `daytona-recursive`:

```bash theme={null}
FLEET_OPENCODE_GO_API_KEY=...
FLEET_OPENCODE_GO_BASE_URL=https://<gateway>/v1
```

For `daytona-managed` and the benchmark profiles:

```bash theme={null}
DATABRICKS_TOKEN=...
FLEET_DATABRICKS_AI_GATEWAY_BASE_URL=https://<gateway>/serving-endpoints
```

## Backend startup

### `Connection refused at 127.0.0.1:8000`

Check what is holding the port and rerun on a different port:

```bash theme={null}
lsof -i :8000
uv run fleet-rlm serve-api --port 8001
```

### Backend refuses to bind a non-loopback host

Launchers default to `127.0.0.1` and reject `0.0.0.0`, LAN addresses, and hostnames other than `localhost`. Pass `--allow-non-loopback-bind` to opt in when running behind a proxy.

### Database preflight fails

`fleet cli` verifies the configured database is at the canonical Alembic head. Recover with:

```bash theme={null}
uv run python scripts/db_init.py
uv run alembic check
```

## Daytona

### Diagnose before a real Turn

Run the doctor to validate settings, database head, provider auth, Volume visibility, mount scoping, and interpreter execution:

```bash theme={null}
uv run fleet doctor daytona
```

It creates one uniquely labelled disposable Sandbox, deletes it in `finally`, and prints only bounded categories and corrective actions.

### Missing Daytona base snapshot

Recursive delegations bootstrap from a reusable snapshot. If it is missing, rebuild it:

```bash theme={null}
uv run fleet-rlm daytona-snapshot --refresh
```

## Turn SSE stream

### Transport `200` but the stream ends with `error`

The Turn stream begins immediately, so a healthy transport status does not imply a successful Turn. When claim or preparation fails, the stream closes with `error` + `finish` chunks carrying one of these messages:

* `Session not found`
* `A Turn is already running`
* `Idempotency key input mismatch`
* `Invalid Skill selection`
* `Turn preparation timed out`
* `Turn is unavailable`
* `Invalid request`

Read the Run id from the `start` chunk metadata, not from a response header.

### Cancelled Turns show no reasoning or output

By design. Cancellation ends the live stream with a single terminal `abort` chunk. The persisted tombstone carries only observed usage, a `cancelled` `data-status` part, and the closed text `Turn cancelled` — never reasoning, code, output, or Tool evidence.

## MLflow tracing

### Traces not appearing in the local server

`fleet cli` starts or reuses a local MLflow server on `127.0.0.1:5001` for the interactive profiles. Backend-only commands (`fleet web`, `fleet-rlm serve-api`) require the tracking server to be started separately.

Benchmark profiles (`daytona-bench`, `daytona-bench-40`) explicitly disable tracing.

### Managed MLflow inputs missing

The `daytona-managed` profile requires `FLEET_MLFLOW_EXPERIMENT_NAME`, `FLEET_MLFLOW_TRACE_CATALOG`, `FLEET_MLFLOW_TRACE_SCHEMA`, `FLEET_MLFLOW_TRACE_TABLE_PREFIX`, and `FLEET_MLFLOW_TRACING_SQL_WAREHOUSE_ID`. Startup fails without them.

## Still stuck?

* File an issue: [github.com/qredence/fleet-rlm/issues](https://github.com/qredence/fleet-rlm/issues)
* Read the source — `src/fleet_rlm/api/` mounts the routes and `src/fleet_rlm/chat/turn_coordinator.py` owns the Turn lifecycle. The [architecture page](/fleet-rlm/concepts/architecture) lists the reading order.