oxo-flow validate#
Validate a .oxoflow workflow file. Checks TOML syntax, rule definitions, and DAG construction (including cycle detection).
Usage#
Arguments#
| Argument | Description |
|---|---|
<WORKFLOW> |
Path to the .oxoflow workflow file |
Options#
| Option | Short | Description |
|---|---|---|
--as-include |
— | Validate as a sub-workflow fragment (skips input-existence checks, the pixi-manifest preflight, and DAG construction; cycle detection still applies) |
--json |
— | Output machine-readable JSON to stdout |
--ai |
— | Enable AI-powered semantic validation |
--verbose |
-v |
Enable debug-level logging (global) |
--quiet |
— | Suppress informational output — the version banner is omitted; the ✓ verdict, warnings, errors, and --json output are unaffected (verified: output is byte-identical with --quiet) (global) |
--no-color |
— | Disable colored output, also respects the NO_COLOR environment variable (global) |
Examples#
Validate a workflow#
Output#
Valid workflow#
✓ pipeline.oxoflow — 5 rules, 4 dependencies
⚠ Warning: The following input files do not exist:
- refs/genome.fa
--json prints the full result object (stdout):
{
"command": "validate",
"workflow": "pipeline.oxoflow",
"valid": true,
"rules": 5,
"dependencies": 4,
"errors": [],
"warnings": [],
"missing_inputs": ["refs/genome.fa"]
}
Invalid TOML syntax#
Circular dependency#
error [E006]: DAG error: cycle detected in workflow DAG: align → sort_bam → align
hint: check for circular dependencies between rules
✗ pipeline.oxoflow — DAG error: cycle detected in workflow DAG: align → sort_bam → align
Wildcard input without a sample domain#
An input containing a sample placeholder ({sample}, {group}, {pair_id}, …)
resolves only when the workflow declares a sample domain
([[sample_groups]], [[pairs]], or sample_pattern). Without one the
run fails mid-flight with a literal brace token, so validate reports
the path as missing instead of approving it:
✓ wildin.oxoflow — 1 rule, 0 dependencies
⚠ Warning: The following input files do not exist:
- {sample}.txt (no sample groups/pairs/sample_pattern declared)
--json includes the same entry in missing_inputs. That field is a
free-text diagnostic list, not a stable machine interface: entries mix
plain paths (file simply absent on disk) with paths annotated with a
trailing (...) reason, so consumers must not exact-match the strings
or split on whitespace — match on the path prefix instead.
Wildcard inputs with a declared sample domain#
When a sample domain is declared ([[sample_groups]], [[pairs]], or
sample_pattern), validate binds every {sample}-class input through the
same expansion and readiness pass dry-run and run use, then reports each
concrete path that does not exist (and is not produced by another rule) in
missing_inputs:
✓ wild.oxoflow — 1 rule, 0 dependencies
⚠ Warning: The following input files do not exist:
- inputs/A.txt
- inputs/B.txt
Exit stays 0 because missing inputs are warnings on the validate surface —
the same contract as the literal-path case above. dry-run --json reports
the identical list in its own missing_inputs field, so a CI gate can catch
the unproducible input before run hard-fails on it.
Unbound wildcard (W024 surfaced in validate)#
A rule that uses a wildcard no rule in the workflow declares a source for
(output = ["out/{sample}.txt"] with no [[sample_groups]], [[pairs]],
sample_pattern, or [[values]] entry) keeps the brace token literal
at run time and then fails with a precise hard error. lint warns about
this (W024); validate — the first gate in the recommended
validate → dry-run → run path — now surfaces the same
W024 diagnostic
so a green validate no longer hides a workflow that cannot run:
✓ p.oxoflow — 1 rule, 0 dependencies
warning [W024]: wildcard '{sample}' has no declared source — it will stay literal at run time and files may be written literally named after the placeholder (rule: step1)
hint: declare a source for the wildcard (sample_pattern in [config], [[sample_groups]], [[pairs]], or a [[values]] table), or remove the placeholder
Warnings keep exit code 0 — only errors fail (the shared CLI exit-code
contract is documented on run). validate scopes itself
to W024 and SCI-AGG-RACE (runnability); the full best-practice sweep
remains lint's job, and the warnings array is empty when
nothing blocks runnability. At run time the corresponding
unbound-placeholder WARN is emitted once per (instance, placeholder):
the multiple render sites within one instance (output pattern + command)
collapse to a single line — the double-print the issue reporter saw —
while each fan-out instance still logs its own line, because the message
names the expanded instance (step1_lane_L1) rather than the template
rule.
Aggregation race (SCI-AGG-RACE surfaced in validate)#
A rule that fans out across a sample, pair, [[values]], or
output_pattern dimension while its declared outputs are not keyed by
that dimension makes every expanded instance write the same concrete
path — the instances race or duplicate work N−1 times. The shape is
statically detectable (no expansion needed), and validate now reports
it with the same detector and code dry-run
uses, so the first gate no longer waves through a workflow that will
crash or corrupt results at run time:
✓ agg.oxoflow — 1 rule, 0 dependencies
warning [SCI-AGG-RACE]: rule fans out per the sample domain — no {sample}/{group} wildcard keys the outputs: … (rule: multiqc)
hint: if the fan-out is unintentional … for a genuine per-element rule, key the outputs by that dimension's wildcard …
--json carries the same finding in warnings. The warning keeps exit
code 0 — it identifies a design defect, not a parse/DAG error — and
--as-include skips it because a standalone fragment does not declare
the parent workflow's fan-out domains. dry-run still prints the full
scientific-preflight sweep; validate surfaces only this
runnability-relevant code.
Notes#
- Exits with code
0on success,1on failure - Validates TOML parsing, rule semantics, and DAG construction
- Missing input files are reported as warnings (not errors). A rule's declared pixi manifest, by contrast, is existence-checked and reported as error E019 (a missing environment file blocks every rule that needs it at run time);
--as-includeskips input-existence checks, the pixi-manifest preflight, and DAG construction, but cycle detection still applies (cycles are semantic errors, not missing files) [wildcard_constraints]entries are compiled with the same helper the expansion engine uses — an uncompilable pattern surfaces as error E020 (defense-in-depth for programmatically constructed configs; TOML-parsed workflows already fail at parse time with a config error)- input/output patterns carrying Snakemake-style inline wildcard constraints (e.g.
{sample:[A-Z]+}) surface as error E021 — the engine's wildcard grammar is{name}only, so the brace group would stay literal text instead of expanding; move the regex into[wildcard_constraints] - a rule with no runnable command —
shellmissing/empty/whitespace-only and no non-emptyscript— surfaces as error E022.E002cannot catchshell = ""because the field is present, yet the engine skips such a rule at run time; this gate is what makes animportthat dropped a Nextflowscript:block fail loudly instead of producing a workflow that validates and then does nothing.transformrules are exempt (their command lives intransform.map/transform.combine) - Relative paths resolve against the workflow file's directory — the same base rules run from — so warnings are accurate even when invoked from another directory. This includes the pixi-manifest preflight:
pixi = "envs/x.toml"is checked at<workflow dir>/envs/x.toml, never against the invoking CWD - Environments and tools are not verified here — the pixi-manifest check only confirms the manifest file exists, not that the pixi binary is installed or that the environment solves. Use
oxo-flow test --deep(checks environment definition files D002 and PATH binaries D003) oroxo-flow env checkfor environment validation - Run
validatebeforerunto catch errors early without consuming compute resources lintis a strict superset: it runs allvalidatechecks plus style linting and secret scanning