# Troubleshooting

Source: https://docs.tradefloor.dev/troubleshooting.html

> Fixes for install errors, missing extras, agents that never trade, refused orders, shares sent as weights, missing history, replay errors and model failures.

Error messages are quoted as tradefloor 0.11.0 prints them. The numbers in them vary from run to run.

## Installation and extras

### No matching distribution

Symptom`pip install tradefloor` ends with `No matching distribution found for tradefloor`.

CauseThe Python running pip is older than 3.11, the oldest version tradefloor supports.

FixCheck with `python --version`, then install into a 3.11 or later environment, for example `python3.12 -m venv .venv`.

### A build from source

Symptompip downloads a `.tar.gz` instead of a wheel, and the build fails with an error about Rust, `cargo` or maturin.

CauseThere's no prebuilt wheel for your platform. Wheels cover Linux x86_64 and aarch64, macOS arm64 and x86_64, and Windows x86_64. Anything else builds from source.

FixInstall a Rust toolchain from [rustup.rs](https://rustup.rs) and run pip again, or use one of the five platforms ([Install](https://docs.tradefloor.dev/install.html#requirements)).

### Brackets in zsh

Symptom`pip install tradefloor[mcp]` stops with `zsh: no matches found: tradefloor[mcp]`.

Causezsh reads the square brackets as a file pattern before pip sees them.

FixQuote the argument: `pip install "tradefloor[mcp]"`.

### Missing extras

SymptomAn import or a call raises an `ImportError` that ends in a `pip install` command, such as `tradefloor.gym needs numpy and gymnasium, and numpy is not installed. Install them with: pip install 'tradefloor[rl]'`.

CauseThe feature needs an optional package that the core install leaves out. The MCP server, the gym environment and every LLM adapter in live mode need one.

FixRun the command in the message. [Optional extras](https://docs.tradefloor.dev/install.html#optional-extras) lists every extra.

### FinRobot on Python 3.12 and later

Symptom`pip install "tradefloor[finrobot]"` stops with `Could not find a version that satisfies the requirement finrobot>=0.1.5`.

CauseFinRobot supports Python 3.10 and 3.11, and tradefloor needs 3.11 or later, so the extra installs on 3.11 only.

FixUse a Python 3.11 environment for live FinRobot runs. Replaying a recorded FinRobot run works without the extra on any supported Python.

## An agent that makes no trades

The scorecard reads `trades=0` and a P&L of 0. Check the end of the scorecard first. If it shows `errors=N`, the agent tried to trade and something failed.

### Acting on the wrong step

SymptomNo errors, no trades, or trades only on the first day.

Cause`obs.step` counts decision steps over the whole run, from 0 to six times the number of days, less one. A check written as `obs.step == 0` to mean "every morning" is true once. `obs.step_of_day` starts again at 0 each day.

FixUse `obs.is_first_step_of_day` for once a day and `obs.step == 0` for once a run.

### Errors on every step

SymptomA warning such as `Agent 'mine' failed on all 120 of its steps, so its score is empty. First error: ...`, and `errors=120` on the scorecard.

Cause`act` raised, or returned something other than a mapping. A list of pairs gives `act() must return a mapping of ticker to order, such as {'AAA': 100} or {'AAA': tf.Limit(100, 25.0)}, or None to trade nothing. It returned a list: ...`.

FixPrint `scores["mine"].errors`, where each line names the step and what went wrong. A step that raised traded nothing, and later steps ran as normal.

### A class passed as the agent

Symptom`tf.evaluate` raises before any market runs: `Agent 'mine' is the class Mine, not an agent. Pass Mine() instead.`

CauseThe agents mapping holds the class, and the harness needs an object with an `act(obs)` method.

FixPass an instance: `{"mine": Mine()}`.

### Limit orders that never fill

SymptomNo errors, and `trades` stays at 0 while the agent sends `tf.Limit` orders.

CauseA limit order waits in the book until the market reaches its price, and `trades` only counts fills. A buy limit well below the current price can wait for the whole run. A new limit on the same ticker replaces the one already waiting.

FixSet the limit price from `obs.price(ticker)`, or send a plain number of shares for a market order that fills at once.

An agent that needs past prices before it acts can also sit out a whole run, as Missing warm-up history explains.

## Rejected orders

A refused order trades nothing. It adds one to the scorecard's `rejected` and a line to `errors`, and other orders from that step still trade.

| Message in errors | Cause | Fix |
| --- | --- | --- |
| step 4: no instrument with ticker "aaa" in this universe | The ticker is not in the market. Tickers are case-sensitive. | Take tickers from obs.tickers. |
| step 2: trade would take leverage to 2.37x, above the 2.00x limit | The order would take gross positions past max_leverage times net worth, 2.0 by default. Also counted in leverage_refusals. | Send a smaller order, or pass max_leverage to tf.evaluate. None removes the limit. |
| step 0: the order for 'AAA' must be a number of shares, a tf.Limit or a tf.Cancel, got '100' (str) | The quantity is a string or a bool. | Send an int or a float. |
| step 0: the order for 'AAB' must be finite, got nan | A calculation produced NaN or infinity, often a division by zero. | Check the inputs to the size calculation, and send nothing when they are missing. |

Once an agent's net worth is zero or below, the leverage limit refuses every order, since leverage on zero net worth is infinite.

A market order bigger than the book can absorb isn't refused. It fills what the book holds and shows up in the scorecard's `partial_fills`, as in `step 2: asked to buy 1,000,000,000,000 AAD; the book held 44,021,201, and the rest did not fill.`

## Shares and portfolio weights

SymptomThe agent trades but the P&L is a few units of currency, with a warning such as `Agent 'mine' asked for fractions of a share (0.2 of AAA, 0.2 of AAB, 0.2 of AAC, ...). act() returns numbers of shares, not portfolio weights.`

Cause`act` returned portfolio weights. `{"AAA": 0.2}` buys a fifth of one share of AAA.

FixConvert each weight to shares at the current price, as below.

Each value `act` returns is a number of shares to trade now. Returning `{"AAA": 100}` at every step buys 100 more shares at every step. To hold a target weight, trade the difference between the target and the current position:

```
import tradefloor as tf

class FifthEach:
    # hold 20% of net worth in each of five names
    def act(self, obs):
        worth = obs.portfolio.net_worth()
        orders = {}
        for ticker, price in zip(obs.tickers, obs.prices):
            target = int(0.2 * worth / price)             # 20% of net worth
            orders[ticker] = target - obs.position(ticker)
        return orders

market = tf.Universe.random(5, seed=111)
card = tf.evaluate({"fifths": FifthEach()}, seed=7, universe=market, days=5)["fifths"]
print(card)
```

```
Scorecard('fifths', pnl=-5,782, return=-0.58%, trades=146, impact=+0.31bps, sharpe=n/a (short run), vol=13.4%, in_market=100%, exposure=1.00x)
```

Five names at 20% each keep the agent at 1.00x exposure. Most of the 146 trades are small top-ups as prices move, because every step sends the gap.

`tf.baselines.rebalance(obs, {"AAA": 0.2, "AAB": 0.2})` does the same job. It also skips trades of less than one share and caps each trade at 2% of the company's average daily volume, which limits what the agent pays in impact.

## Missing warm-up history

SymptomAn agent that needs, say, 20 days of prices trades nothing for the first 20 days, or nothing at all in a short run. `obs.history.bars("AAA", last=20)` returns fewer than 20 bars, and none at the first step.

Cause`tf.evaluate` and `tf.rank` start at day 0 with no history unless asked for one.

FixPass `history_days=20`. The market then runs 20 untraded days before day 0, and `obs.history` holds their daily bars at the first decision, labeled day -20 to day -1.

With a warm-up, the scored days carry on from the warmed market. On the same seed they're different days from a run without one, and the scorecard records `history_days` to show it. A warm-up can be up to 2520 days, which is ten 252-day years. `obs.history` never holds the day in progress, and each scored day is added after its close. The reference agents and `tf.StrategySpec` strategies keep their own price history and ignore `obs.history`.

While the history is still empty, `obs.history.bars()` returns an empty list even for a ticker the market doesn't list, so check tickers against `obs.tickers`.

## Replay mismatches

### Manifest refusals

`RunManifest.reproduce()` raises a `ValidationError` naming the part that disagreed.

| Message starts with | Cause | Fix |
| --- | --- | --- |
| this build does not reproduce the manifest's era | The manifest was written on a release whose default preset or arithmetic differs from this one. The message names the version and platform that wrote it. | Install that version, or rebuild the run from its named preset, seed and universe. |
| this manifest ran model preset 'pt-vN', which this build does not ship | The preset is newer than this release, or came from a development build. | Install a release that ships the preset. |
| model preset 'pt-vN' disagrees between this manifest and this build | One side was a development build that carries other values under the same name (Preset names and preset values). | Reproduce on the build that wrote the manifest. |
| the replay ran but did not rebuild the recorded market | The inputs matched but the market didn't. If the message says the draw counts differ, the order log does not cover everything that happened to the engine. | Replay part of the log with tf.replay(log, ..., until=n) and find the first step that differs. |
| the universe in this manifest does not match its recorded fingerprint | The file was edited after it was written. | Get an unedited copy. |

On 0.8.5 and later, a traded run recorded before 0.8.5 matches up to its first trade and then differs, since 0.8.5 changed how fills reach the market. Replay such a run on the release that recorded it.

### Refused LLM replays

A replay looks up each answer by a digest of the exact observation the model was shown. If it finds no answer, it raises `ReplayMiss`. That stops `tf.evaluate` with a note naming the step, the agent and the seed, so the agent is never scored as if it had held cash.

| Message starts with | Cause | Fix |
| --- | --- | --- |
| no recorded response for step N (day D, digest ...) | Something that feeds the observation changed after recording: the seed, the universe, history_days, the instructions or the market settings. A recording made before 0.8.5 can fail this way too, because 0.8.5 changed the observation the model is shown. | Replay with exactly the call that recorded it, on the release that recorded it, or record again live. |
| this transcript was recorded against a different simulation preset | The replay runs another preset, often the default. | Pass the recorded preset, as in tf.evaluate(..., model="pt-v19"). |
| this transcript was recorded under observation payload version | The recording was made by a release with another observation payload. Since 0.8.5 each recording names its payload version. | Replay on the release named in the message. |
| the recorded entry for step N (day D, digest ...) holds a null response | The live call failed during recording, and the failure was recorded. | Record the run again live. |

## Model-provider failures

### Failed model calls

SymptomThe scorecard has `errors=N` and few or no trades, with lines such as `step 12: FrameworkError: openai-agents raised APIConnectionError instead of returning a decision: ...`.

CauseThe call to the model never completed: no network, a missing or wrong API key, a rate limit or a timeout. The adapters add no retry of their own, and `tf.evaluate` scores the step as one that traded nothing and carries on.

FixRead the exception type at the end of the line, fix the key, quota or connection, and run again. Compare runs by their `errors` count as well as their P&L, because a failed call and a decision to hold both trade nothing.

### Unreadable decisions

SymptomLines in `errors` such as `DecisionError: no JSON object in the framework response`, `no 'actions' key in the decision (keys present: ...)` or `the framework returned an empty response, so there is no decision to validate`.

CauseThe model answered, but its answer wasn't a decision. A decision is an `actions` list and an optional `rationale`, and the adapter doesn't guess what the model meant.

FixAsk for that shape in the instructions, or use the framework's structured output. An answer of `{"actions": []}` is a valid decision to hold.

### Refused actions

SymptomThe decision traded, and `errors` and `rejected` also count one action, for example a symbol the market does not list.

CauseSince decision schema 2 a bad action inside a good decision is refused on its own, and the rest of the decision trades.

FixThe `refused action:` line in `errors` gives the reason.

### The PydanticAI request budget

Symptom`UsageLimitReached: the run at step N (day D) stopped on its request budget of ...`

CauseThe PydanticAI adapter caps the requests one decision may make, at 8 by default.

FixRaise `request_limit` on the adapter, or pass `None` to remove the cap.

### Adapter warnings

| Message | Cause | Fix |
| --- | --- | --- |
| ... is starting a new run (day 0, step 0) but still holds N steps of prices from an earlier one | One adapter ran a second evaluate or World, so its model sees the first market's prices in its returns. | Build a new adapter for each run, as tf.rank does with its factory. |
| this agent has output validators registered with @agent.output_validator | PydanticAI refuses to change the output type of an agent with an output validator. | Pass bind_output_type=False to keep your output type. tradefloor still validates the decision. |
| GraphInterruptedError | A LangGraph graph paused for a human. The market moves on as soon as act returns, so there is nothing to resume. | Give the adapter a graph that decides without an interrupt. |
