m/market labResearch, with a record.
Source on GitHub ↗

Troubleshooting

Find the message or symptom, then the fix. For anything else, run the command again with --log-level debug (or call sim_platform.diagnostics.configure_logging('debug') in Python): handled failures then log their full traceback. Never paste API keys into an issue.

Installing and starting

Symptom Cause and fix
native market library not built while installing No C++17 compiler was found, so the wheel is pure Python. Install the platform wheel (py3-none-<platform>), or a compiler (Xcode command-line tools, build-essential, Visual Studio Build Tools) and reinstall
OSError loading libitch_market The native library is missing or for another architecture. Run make all in a checkout, or set MARKET_LAB_NATIVE_LIBRARY to the library's path
macOS says the App "cannot be opened" A local build is ad-hoc signed. Right-click the App and choose Open, or use a signed and notarised release
Windows SmartScreen warns about the installer Beta installers are not yet signed; choose More info, then Run anyway, after checking SHA256SUMS
The AppImage does not start Run chmod +x on it; on older distributions install libfuse2
The Desktop window is blank on Linux Install the Qt runtime libraries (libxcb-cursor0, libxkbcommon-x11-0, libegl1)

Data and markets

Symptom Cause and fix
Times must be distinct or a CSV is refused See price-bar input: one row per bar, a date column, OHLCV columns
replay source file changed since the run The recording changed after the run. Restore the original file; verify_run() shows which input differs
replay execution implementation mismatch The run was recorded with other execution rules (an older version). Replay it with the version in its lineage (run_lineage()['inputs']['code'])
The first experiment on a large ITCH file starts slowly Its SHA-256 is computed once for the run's lineage and cached; later runs start at once
runs are not comparable in an evaluation The runs differ in a setting named in the message (cash, costs, window, symbol). Rerun them with equal settings

Agents and models

Symptom Cause and fix
AUTH_FAILED The model key is wrong or missing. Store it again under Settings → Model credentials or with market-lab credential
RATE_LIMIT or PROVIDER_TEMPORARY repeated, then RETRY_EXHAUSTED The provider refused requests. Raise retry.max_attempts, lower concurrency, or use a local model
base_url host must be localhost or a private IP address A local model profile must point at this machine or a private network; for a hosted service use the openai-responses provider
A local model's replies end the run with FORMAT_ERROR The model did not return valid tool calls. Use a model with tool-calling support (vLLM --enable-auto-tool-choice, Ollama tool models) and rehearse first
The run stopped with reason budget Its model budget was spent; see model_usage['budget_exceeded'] and raise budget if intended
AGENT_DEPENDENCY_MISSING The Agent imports a package its environment lacks. Add it to the project's requirements and prepare the environment again
Agent environment is not ready Prepare it: Agents → Prepare, or prepare_agent_environment()
... needs the network, but offline mode is on MARKET_LAB_OFFLINE is set. Use a local model server, a wheelhouse or an offline Python archive, or unset it
no Agent sandbox is available on this machine Install bubblewrap or Podman (Linux), or remove sandbox from the settings; macOS uses sandbox-exec, which is built in
An Agent run looks stuck in Live mode Live market time keeps moving while the model thinks. Use turn-based pacing (speed='turn') to measure decisions without speed

Results

Symptom Cause and fix
No equity curve on a result The run had no archived bars, or started with positions; figures that need the curve are left empty
A Sharpe ratio is marked unreliable Fewer than 20 daily returns; use a longer window or more recordings
verify_run() reports code_changed The code now running differs from the run's; the stored run is unchanged, but Replay may disagree
Results differ between two runs diff_runs() lists every setting, prompt, model version, input and code difference

Section index · All documentation

Maintained source: docs/user-guide/troubleshooting.md