Troubleshooting

Install and imports

``brushline: command not found`` — activate the virtual environment and reinstall with python -m pip install -e .. Check brushline status.

Optional import errors — install the appropriate extra, for example python -m pip install -e ".[geo,opt,web]". The base package intentionally keeps the web and optimization paths optional.

Docs build fails — install docs/requirements.txt and run python -m sphinx -W -b html docs docs/_build/html. The build treats warnings as errors.

Private network artifacts

The network instance does not appear — the studio only exposes it when runtime/private/bc-network/model/ exists. A clean public checkout does not include it.

A builder reports missing cache files — the private OSM, VRI, DEM, or network cache is absent. Do not fabricate it; restore the approved private cache or stay on the synthetic demo.

I need to share a result — stop. Run Release audit, read Private and public boundaries, and do not publish network-derived artifacts before approval.

Solvers and performance

The MILP times out — exact stateful MILP is intended for small instances. Use the Fresh Solutions heuristic or cluster repair for larger cases, and report the search status rather than calling it optimal.

A heuristic result differs from an exact result — they are different methods. Check the solver status, seed, instance size, and whether the exact model is still within its intended range.

A run is slower than expected — the network builder, scenario sweeps, and 590-segment policy experiments take minutes. Use the focused builders and cached artifacts rather than rebuilding the full network for every change.

Studio and ports

Port already in use — in this workspace 8765 is fresh-irss-demo, 8799 is Nemora, and 8801 is Brushline. Stop the conflicting service or use another port.

The studio shows stale data — restart the service after regenerating artifacts, and check the static asset version in the page source.