Troubleshooting

This page lists common failures and the first checks to run.

Check First

Run these before debugging a full GWAS command:

uv run g --help
uv run g regenie --help

This experimental Rust CLI/config branch does not expose the previous g config init, g config validate, or g config explain helper commands.

For GPU runs, check the target node:

hostname
uv run python -c "import jax; print(jax.devices())"

For input-dependent failures, confirm the required files exist and are non-empty:

test -s /path/to/genotypes.bgen
test -s /path/to/phenotypes.tsv
test -s /path/to/regenie_step1_pred.list

g regenie Rejects An Option

Check uv run g regenie --help for the currently supported CLI surface on this experimental Rust frontend branch. Familiar REGENIE flags that are absent from help are not accepted yet.

Common absent flags include --bed, --pgen, --keep, --remove, --extract, --exclude, --catCovarList, --test, --t2e, and --spa.

See Compatibility for the supported and unsupported surface.

TOML Config Fails To Parse Or Validate

Check that the file is valid TOML and that option names use the current sectioned config surface. The current Rust frontend validates config as part of constructing the g regenie run; it does not provide a separate config-only validation command.

g rejects unknown sections, unknown keys, empty selected column names, and binary-only options in quantitative mode. For CLI-to-TOML spelling, see Configuration.

g regenie Prints Error: ...

Runtime failures are reported as a concise stderr line and exit code 1, not a Python traceback. Re-run with telemetry or logging enabled when you need the structured failure event and detailed diagnostics:

[diagnostics]
telemetry = "profile"

Diagnostic logs are written under the output run root.

Missing Step 1 Predictions

g does not implement REGENIE Step 1. Produce prediction lists with upstream regenie and pass the list through --pred.

For repository fixture-data examples, use the development recipes listed in Quickstart.

Binary Phenotype Coding Fails

Binary traits must use REGENIE-style coding in the phenotype file:

Other non-missing values are rejected rather than silently recoded. Confirm the selected phenotype column, missing-value tokens, and delimiter before debugging the binary kernel.

Sample Alignment Fails

Check:

• the required Oxford .sample file is supplied with --sample;
• the sample, phenotype, covariate, and prediction inputs contain non-empty FID and IID values;
• each (FID, IID) pair is unique in every input;
• binary phenotypes use REGENIE-style 1 = control, 2 = case coding;
• selected phenotype and covariate columns are present and spelled exactly.

See Input Files.

Packed8 Eligibility Issues

Packed8 selection and BGEN compatibility validation are automatic. Packed8 requires unphased, biallelic, diploid, 8-bit BGEN with no missing calls. Otherwise-supported biallelic diploid Layout-2 data with missing calls, phased probabilities, or a different bit depth uses dosage delivery. Multiallelic, non-diploid, or otherwise unsupported input fails instead. There is no manual packed8 eligibility override.

GPU Is Not Used

Probe JAX on the same kind of node where the scan runs:

uv run python -c "import jax; print(jax.devices())"

Common causes:

• command ran on a login node without NVIDIA devices;
• CUDA-enabled JAX or its plugin dependencies are unavailable or incompatible;
• NVIDIA driver and installed JAX CUDA extra are incompatible;
• scheduler job did not request or receive a GPU;
• [compute].device resolved to "cpu" in the effective config.

If the accelerator is visible but performance does not improve, check whether BGEN decode, transfer, or output dominate. See GPU and Clusters and Performance Guide.

Out Of Memory

Reduce the largest shape-driving knobs first:

[trait]
bsize = 4096

[compute]
firth_batch_size = 256

For GPU runs, also check whether the command is repeatedly recompiling with different shapes or keeping too many results in flight. Use [diagnostics].telemetry = "profile" on a representative bounded run before changing production settings.

Resume Does Not Reuse Existing Output

Every resumable run writes run_manifest.json and effective_config.toml. Resume only when the manifest and execution-plan-affecting inputs still match.

Enable resume:

[output]
resume = true

Resume always performs strict manifest and chunk-file reconciliation.

Common causes:

• no run_manifest.json exists;
• the output run directory exists but was not produced by the same analysis;
• a source file changed size or modification time;
• a trait, covariate, binary correction, output, dtype, or multi-phenotype sample-mode option changed.

See Resume and Manifest.

Output Looks Missing

--out is a prefix. The default run root is:

<out>.g/

Look for per-phenotype directories such as:

trait_0001_phenotype.regenie2_linear.run/
trait_0001_phenotype.regenie2_binary.run/

Results are the parts/part_*.parquet dataset inside each phenotype run directory. See Output Files.

Some Parquet Parts Are Missing

If a run was interrupted or storage failed, rerun the same command with:

[output]
resume = true

Resume reconciles committed manifest chunks with Parquet files before writing the missing work. If writes continue to fail, inspect free space and permissions for the run directory and destination filesystem.

Approximate Firth Reports a Failed Correction

CORRECTION_METHOD = firth_approximate with CORRECTION_STATUS = failed means score testing completed but the fallback correction did not produce a valid corrected statistic for that variant. First checks:

• confirm --bt --binary-fallback firth_approximate was intended;
• compare candidate density by changing --pThresh on a small subset;
• inspect profile logs for Firth solver iteration or line-search failures;
• compare against upstream REGENIE only with equivalent Firth settings.

Documentation Build Fails

Documentation builds are part of the development workflow:

uv sync --group docs
just docs-build

Most failures are stale Markdown links or pages missing from zensical.toml. The generated documentation_rendered_website/ directory is ignored by git and can be removed when you need a clean local rebuild.