Troubleshooting
Symptom first. Each entry says what it usually means and what to do; the how-to guides carry the detail.
Installation
``ModuleNotFoundError: geopandas`` when building from a shapefile.
Install the geo extra: python -m pip install -e ".[geo]". CSV and Parquet inventories need
nothing extra, so this is worth avoiding if you can.
``ws4`` not found after installing.
The editable install places the console script beside the interpreter it was installed into. Confirm
you are in the same environment (python -c "import ws4; print(ws4.__file__)"), or run the module
directly (python -m ws4.cli --help).
The mixed-integer bound complains about ``scipy``.
ws4 optimize --mip-bound needs the opt extra: python -m pip install -e ".[opt]".
Building a dataset
``validate`` reports a table or a column. The dataset is a contract and is checked on the way in. Fix the recipe or the inventory and recompile rather than editing Parquet: the manifest records the inputs’ digests, and downstream commands trust it.
Blocks or fragments are missing from the simulation.
Look at fragments.parquet: an age outside the curves’ domain, a zero area, or a block id that
appears in no topology row are the usual causes. ws4 validate names them.
Nothing is operable.
Check treatments.parquet. begin and end come from the recipe’s minage and maxage,
and end of zero or less means no upper bound. If the age windows exclude your stands, the search
has nothing to choose.
Simulating
A simulation is fast but the accounts are flat.
Check the schedule’s offset column: it is the number of years after the start of the simulation
(offset 0 is the first simulation year), not an accounting-period index. A schedule written in period
indices treats the wrong offsets, and a period column is rejected outright.
The treatment was applied but no product appeared.
The product belongs to the stratum the treatment moves the fragment to, so a treatment whose
transition assigns no new track produces on the track it left. Check the recipe’s transition
assigns.
Optimizing
The objective is zero but the answer is wrong.
0.0 means every target is met. An unconstrained year or account is therefore free, and the search
will spend it arbitrarily. Add the targets you actually care about
(Write targets).
The search barely moves from its starting point.
Weights are unbalanced: one term is so expensive that every move is worse. Run ws4 calibrate, or
lower that term’s weight, or switch shape to linear for a term that should be a soft pull.
A target is always ``below``. Test it alone. If it is still below, the estate cannot deliver it in those years: loosen the floor, move it to a later period, or extend the horizon.
The run takes far longer than the horizon suggests.
A patch target keeps one patch state per targeted period; a route build account, a duplicate
account, or an edge-contrast element makes every evaluation a whole-schedule pass. Narrow the
windows, keep those out while tuning, or use --time-limit deliberately rather than as a safety
net.
A run is not reproducible.
Pin the whole configuration: seed, horizon, targets file, weights, topology, patch accounts, and the
parallel settings. A different workers or islands value is a different search.
Watching
The live view shows nothing.
It needs a terminal; piping to a file buffers until exit. Use --plain for a single frame.
An account has no window. The name does not match a target. Account names are exact and case-sensitive.
Patch targets
``KeyError`` on a ``patch.*`` account.
The class label comes from size_classes; bounds 10, 50, 150 produce 0_10, 10_50,
50_150. A label you never defined cannot be targeted.
Every patch is one block.
search_distance defaults to 0, which joins only blocks whose polygons touch. Raise it if your
topology’s blocks are separated by real gaps you want treated as touching.
Routing
Everything is surplus, or haul cost is zero. No eligible destination is reachable from the block’s linkage vertex. Check the eligibility table and the linkages file.
Build cost appears in one period only. That is the model: build once, maintain while used.
Carbon
``ModuleNotFoundError: libcbm``.
Carbon is an optional extra. Install ws4[carbon]; a core install deliberately does not
import the engine.
A carbon run fails on ``CARBON-UNMATCHED-TRACK``. The package and compiled dataset disagree on an exact track name. Rebuild the package against that dataset; do not rename a track by hand.
The run complains that the CBM defaults hash differs.
The package and the installed defaults database are not the same. Rebuild the package, or
use --allow-defaults-mismatch only for an explicit comparison and record it in the
study provenance.
A carbon target is rejected before the search.
Add --carbon-package. For an HWP or whole-system target, also add
--carbon-hwp <yaml>; a missing lifecycle config is a configuration error, not a
zero-emission result.
The ledger and the exact carbon run differ after harvesting.
The ledger is block-exact; a full run allocates an event by classifier set and area. When
several blocks share a source track, the event can be distributed across stands. Verify
the final schedule with ws4 carbon.
HWP accounts are missing or all zero.
Pass --hwp-config (or --carbon-hwp). If the configuration is present but the run
has no harvest, the product pools stay at zero, which is expected. Check the
carbon.hwp.inflow series first.
A GCBM comparison is empty or misleading. Check the GCBM 2.5.x schema and whether the project has the same footprint. The reader is tabular and is a bridge check; it is not a model-parity test.
Getting help
If the symptom is not here, the reference page for the subsystem is the next stop
(Reference), and the repository’s notes/ directory records the measurements and
the decisions behind the behaviour. For a bug, the issue tracker; include the summary.json, the
report_targets.csv, and the command line you ran.