Troubleshooting
===============

This page covers common wrapper issues and fixes.

``Refusing to overwrite existing file: pleb.toml``
--------------------------------------------------

Cause:

- ``pleb init`` was run where ``pleb.toml`` already exists.

Fix:

- use ``--force`` if overwrite is intended.

``missing_required=home_dir,singularity_image`` from ``doctor``
----------------------------------------------------------------

Cause:

- required path keys are absent in resolved config.

Fix:

- set under ``[paths]``:
  - ``home_dir``
  - ``singularity_image``

``Unsupported run.mode=...``
----------------------------

Cause:

- unsupported ``run.mode`` value.

Fix:

- use one of: ``pipeline``, ``ingest``, ``workflow``, ``qc-report``.

Run executes but behavior is unexpected
----------------------------------------

Likely causes:

- key mapped differently than expected,
- same key set in multiple sections,
- advanced key missing in UX aliases.

Debug steps:

1. run ``pleb explain --config pleb.toml``
2. move critical advanced keys into ``[pipeline]`` explicitly
3. rerun ``pleb doctor``
4. pilot run on small pulsar subset

Workflow mode fails to find file
--------------------------------

Cause:

- ``[workflow].file`` missing or wrong path.

Fix:

- set valid path, e.g.
  ``configs/workflows/branch_chained_fix_pqc_variants.toml``.

Preset merge gives unexpected values
------------------------------------

Cause:

- deep-merge override replaced scalar/list at same path.

Fix:

- inspect ``pleb.toml`` after applying preset,
- reapply intended local edits,
- keep a project baseline preset for your team.

When to fall back to legacy config files
----------------------------------------

Use legacy run/workflow TOML directly when:

- you need advanced keys not yet modeled in UX sections,
- you are validating behavior parity against historical runs,
- you are debugging low-level mode-specific behavior.

The wrapper is additive, not mandatory.