Troubleshooting

Symptoms are grouped by where they appear on the path from install to export, with the most common newcomer failures first. Each entry names the cause and the fix command.

🚧 Install And Environment

uv sync fails

Cause: Python 3.12 or newer is not on PATH, or uv is missing. Fix: Confirm the Python version, then rerun:

uv sync --all-extras --group dev

If uv is missing, install it from the official Astral package instructions, open a new shell, and rerun the command.

Installer reports a missing prerequisite

Cause: The install scripts require git and uv on PATH. Fix: Install the named prerequisite, then rerun the same install command. Set DISPATCHATLAS_HOME before rerunning when the checkout should live outside the default user data directory.

Update reports changes but does not apply them

Cause: Update checks are read-only by default. Fix: Set DISPATCHATLAS_REF to a release tag or full 40-character commit SHA, then apply the detached-checkout update explicitly:

$env:DISPATCHATLAS_REF = "<release-tag>"
.\scripts\installer\update.ps1 -Apply

export DISPATCHATLAS_REF="<release-tag>"
scripts/installer/update.sh --apply

Uninstall refuses a target

Cause: The uninstall scripts refuse empty paths, filesystem roots, home directories, and directories without the DispatchAtlas workspace sentinel. Fix: Set DISPATCHATLAS_HOME to the installed checkout path and rerun the uninstall command.

📦 Imports

ModuleNotFoundError: No module named 'dispatchatlas'

Cause: The workspace is not synced, or the script runs under a Python interpreter outside the project environment. Fix: From the repository root, sync and run scripts through uv so the project environment is active:

uv sync --all-extras --group dev
uv run python your-script.py

MissingOptionalDependencyError when creating a solver

Cause: Optional heavyweight backends (exact solvers, learning estimators) stay behind extras and are probed at runtime, never imported during package import. The error names the missing extra, its purpose, and any licensing note. Fix: Install the named extra (for example exact, exact-commercial, or learning) or select a solver whose backend is present. Solver dependency declarations are listed in solver system.

🧪 Campaign Configuration And Execution

CampaignConfigError when validating a campaign

Cause: A configuration field fails validation — an empty id, a non-positive seed or budget, duplicate stopping-protocol names, or an empty benchmark, solver, or objective list. The error carries the failing field path. Fix: Correct the named field. The campaign engine page documents every configuration block, and experiments/configs/smoke-pilot.json is a complete working example:

uv run dispatchatlas-lab validate --config experiments/configs/smoke-pilot.json

KeyError when fetching a benchmark problem

Cause: The problem id is not in the provider's catalog, or a plain string was passed where a ProblemId is expected. Fix: Wrap the id (provider.get_problem(ProblemId("smoke-job-shop-0"))) and list the available ids first with provider.list_problem_ids() — see the tutorials.

Full campaign refuses to execute

Cause: A campaign at the full stage fails closed with full-campaign execution requires statistical design approval until that approval is recorded on the configuration. Fix: Run at the smoke or pilot stage for local checks, or record statistical design approval per release readiness before enabling full execution.

Resume re-plans instead of skipping completed runs

Cause: The checkpoint at .checkpoints/{campaign_id}.json is guarded by a configuration hash; any configuration change invalidates it rather than silently reusing it. Fix: Keep the configuration unchanged to resume, or accept a fresh plan under the changed configuration. The workspace contract is described in reproducible campaigns.

📤 Exports, Reports, And The Site

Analysis export reports a missing checkpoint

Cause: The dispatchatlas export command expects a completed campaign directory with checkpoint.json, plan.json, environment.json, and result records. Fix: Point --campaign-dir at the campaign result directory rather than its parent, or rerun the campaign:

uv run dispatchatlas export `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\exports\smoke-pilot `
  --authorized-output-root .\exports `
  --tier core

If --target-dir is outside the current working directory, pass an explicit --authorized-output-root that contains the destination.

Portal data validation fails

Cause: The static site assets are out of step with the portal result export. Fix: Regenerate the static assets. The command reads the committed disclosure-filtered result export at exports/portal-results.json by default, so it runs with no arguments:

uv run python tools/build_site_assets.py

Pass --result-source to publish a different disclosure-filtered portal-results.json export:

uv run python tools/build_site_assets.py --result-source .\path\to\portal-results.json

If the command reports dispatchatlas site-assets: error, check that --result-source (or the default exports/portal-results.json) points to an existing portal-results.json file generated by the analysis export path.

Portal redaction gate fails

Cause: A token that does not belong on the public surface reached portal data, so the build fails closed to keep the published face reading as a generic scheduling and optimization toolkit. Fix: The error lists each offending artifact, field path, and token. Redact the offending field in the builder that emits that artifact (under tools/portal_contract.py or its source evidence) so only public-safe derived evidence reaches portal data, then regenerate:

uv run python tools/build_site_assets.py

This failure is different from a missing portal export: passing a different --result-source does not clear it — the offending token must be removed at its source.

The site build cannot find a page

Fix: Run the site contract tests and the documentation build:

uv run pytest tests/site
npm --prefix site run build
npm --prefix site run check

A solver is missing from recommendations

Cause: Selection filters on metadata. Fix: Check the solver's metadata for objective support, required capability tags, optional dependency status, and evidence-tier visibility in solver system.

Still stuck? See the FAQ or open an issue on the GitHub repository.