Error Handling & Diagnostics

Keep this simple: preview what will happen, fix inputs, and read the error.

Quick Checklist

• Render dry‑run: bpm template render --dry <id> to preview actions and catch Jinja issues.
• Provide params: add --param KEY=VALUE (repeatable) for required inputs.
• Correct mode: use a project (project.yaml) or --out /tmp/out for ad‑hoc.
• Right template id: bpm template list to confirm available ids in the active BRS.

Common Render Errors

• Undefined variable: Jinja error like “’x’ is undefined”.
  • Fix: pass --param x=... or set a default in template_config.yaml under params:.
• Invalid --param format: “Invalid –param ‘x’ Expected KEY=VALUE.”
  • Fix: use --param name=value (no spaces around =).
• Missing dependencies: “Missing required templates: demux_bclconvert”.
  • Fix: render/run the listed templates first, or remove the dependency.
• Missing source file: “Template not found: run.sh.j2”.
  • Fix: ensure the file exists in the template folder and mapping is correct.
• Jinja syntax error: “Jinja syntax error in run.sh.j2:12: unexpected …”.
  • Fix: correct the template syntax; keep `` for values.

Tip: Use placeholders in render.into like ${ctx.project.name}/${ctx.template.id}/ to avoid hard‑coding paths.

Common Run Errors

• Entry not found: “Command failed: ./run.sh … No such file or directory”.
  • Fix: ensure you rendered first; mapping run.sh.j2 -> run.sh must exist.
• Permission denied: “./run.sh: Permission denied”.
  • Fix: BPM auto‑chmods the run.entry. Make sure run.entry is set (e.g., run.sh) and the file renders.
• Tool not found: errors from your script (e.g., “nextflow: command not found”).
  • Fix: load modules/conda/container in hooks or at script start.
• Non‑zero exit: BPM prints stdout/stderr from the script when it fails.
  • Fix: read the printed sections; re‑run after addressing the root cause.

Publish Errors

• Bad resolver spec: “Publish entry ‘X’ missing ‘resolver’ key”.
  • Fix: add resolver: to each publish item in template_config.yaml.
• Resolver import/function missing: “Function ‘main’ not found …”.
  • Fix: check the dotted path (e.g., resolvers.fastq_dir:main) exists in the active BRS.

Where To Look

• Render folder: under render.into resolved in project/ad‑hoc mode. Check generated files and outputs.
• Console output: on failures, BPM prints a clear “Error: …” with stdout/stderr for run.
• Project state: project.yaml shows saved params, template status, and published results.
• Ad‑hoc meta: bpm.meta.yaml is written in --out for provenance.

Reproduce Minimally

• Show plan only: bpm template render --dry <id>
• Use a clean out dir: bpm template render --out /tmp/out <id> then inspect files in /tmp/out.
• Add one param at a time: --param key=value to pinpoint the offending variable.

How CLI, project.yaml, and template_config.yaml interact

• template_config.yaml: defines defaults (params), where files go (render.into), what to render (render.files), and what to run (run.entry).
• project.yaml: defines project identity (name, project_path) and stores last params and published outputs.
• CLI: --param overrides values for the current render/run; --dry previews; --out switches to ad‑hoc mode (no project changes, writes bpm.meta.yaml).

Simple rule: if render fails, fix parameters or templates; if run fails, read stdout/stderr and fix your script or environment.