Common Fatal Errors and Fixes

Table of Contents

• 1. Structured Validation Errors (ERROR <CODE>)
• 2. High-Frequency Fatal Messages (Runtime Paths)

Use this page to map error output to concrete fix steps.

1. Structured Validation Errors (ERROR <CODE>)

Validation and CLI-combination failures use:

ERROR <CODE> | key=<yaml.path or -> | file=<path[:line] or -> | message=<...> | hint=<...>

Code reference:

Code	Meaning	Typical Fix
CLI_USAGE_INVALID	Invalid argument combination	Run pic.flow <command> --help and follow required flag groups.
CFG_MISSING_SECTION	Required YAML section missing	Add section from examples/master_template/*.yml.
CFG_MISSING_KEY	Required YAML key missing	Add required key at the reported path.
CFG_INVALID_TYPE	Wrong YAML value type	Change scalar/list/mapping type per contract docs.
CFG_INVALID_VALUE	Unsupported value/range	Use allowed enums/ranges from reference pages.
CFG_FILE_NOT_FOUND	Referenced file/path is missing	Fix path or create file.
CFG_GRID_PARSE	Grid payload/format error	Fix block count, dimensions, or coordinate rows.
CFG_INCONSISTENT_COMBO	Conflicting options/keys	Align related flags/keys (periodic pairs, scheduler, process counts).

2. High-Frequency Fatal Messages (Runtime Paths)

Message fragment	Likely cause	Fix command(s)
[FATAL] --post-process requires --run-dir when not used with --solve.	Post-only run missing input run directory	pic.flow run --post-process --run-dir runs/<run_id> --post post.yml
[FATAL] Could not automatically identify required config files in <run>/config	Missing/renamed case.yml, monitor.yml, or *.control	Re-run solve stage or restore expected files under runs/<run_id>/config/.
[FATAL] Source data directory for post-processing not found or empty	Post source data path points to missing/empty solver output	Verify monitor output directory and existing solver output files.
‘[FATAL] Unsupported scheduler ’<x>'. Only Slurm is supported in v1.\ilinebr </td> <td class="markdownTableBodyNone">cluster.ymlhas unsupported scheduler type \ilinebr </td> <td class="markdownTableBodyNone"> Setcluster.yml -> scheduler.type: slurm. \ilinebr </td> </tr> <tr class="markdownTableRowOdd"> <td class="markdownTableBodyNone">[FATAL] In cluster mode, –num-procs must be 1 (auto) or exactly nodes*ntasks_per_node (...)\ilinebr </td> <td class="markdownTableBodyNone"> MPI count mismatch against cluster resources \ilinebr </td> <td class="markdownTableBodyNone"> Set-n 1or set-ntonodes * ntasks_per_node`.

1. Standard Extension Workflow

1. Run config-only checks first:

./scripts/pic.flow validate --case case.yml --solver solver.yml --monitor monitor.yml --post post.yml

1. Preview launch plan:

./scripts/pic.flow run --solve --post-process --case case.yml --solver solver.yml --monitor monitor.yml --post post.yml --dry-run

1. If cluster path is used, validate cluster.yml separately:

./scripts/pic.flow validate --cluster cluster.yml

Related pages:

• Tutorial: Your First Simulation (Flat Channel)
• Configuration Contract (YAML -> Generated Artifacts -> Runtime)
• The Conductor Script: pic.flow
• Testing, Smoke, and Quality Gates Guide