Validate Your YAML (Linter)

Catch YAML errors before committing or running jobs

The Valohai linter catches syntax errors, indentation issues, and configuration mistakes in your valohai.yaml before you commit or launch a job.

It's faster to fix a typo locally than to wait for a job to fail in the cloud.

---

Why Use the Linter?

Catch errors early: Find syntax mistakes, missing required fields, and invalid configurations before execution.

Save time and money: Avoid spinning up expensive GPU instances only to have them crash due to a YAML typo.

Learn YAML syntax: The linter explains what's wrong and where, helping you understand YAML structure.

---

Run the Linter

Make sure you have the Valohai CLI installed and you're in a directory linked to a Valohai project.

Then run:

vh lint

The linter will scan your valohai.yaml and report any issues.

---

Common Errors the Linter Catches

Indentation errors

YAML is whitespace-sensitive. The linter catches misaligned blocks:

# ❌ Incorrect indentation
- step:
    name: train
  image: python:3.9  # This line should be indented 4 spaces

# ✅ Correct indentation
- step:
    name: train
    image: python:3.9

Missing required fields

Steps must have name, image, and command:

# ❌ Missing image
- step:
    name: train
    command: python train.py

# ✅ Complete step
- step:
    name: train
    image: python:3.9
    command: python train.py

Invalid parameter types

Parameters must specify a valid type:

# ❌ Invalid type
parameters:
  - name: learning_rate
    default: 0.001
    type: number  # Should be 'float'

# ✅ Valid type
parameters:
  - name: learning_rate
    default: 0.001
    type: float

Syntax mistakes

Forgotten colons, quotes, or brackets:

# ❌ Missing colon after 'command'
- step:
    name: train
    image: python:3.13
    command
      - python train.py

# ✅ Correct syntax
- step:
    name: train
    image: python:3.13
    command:
      - python train.py

---

Example Linter Output

When you run vh lint, for a valid valohai.yaml you'll see output like this:

$ vh lint
😼  Success! /Users/myuser/Projects/ml-project/valohai.yaml: No errors

---

What the Linter Doesn't Catch

The linter validates YAML structure and Valohai-specific syntax, but it can't catch:

• Logic errors: If your command references a file that doesn't exist, the linter won't know

• Runtime issues: Missing Python packages or incorrect paths will only surface during execution

• Input availability: The linter doesn't check if the input URLs actually exist

Think of it as a spell-checker, not a code reviewer.

---

Best Practices

Lint before every commit: Make it part of your workflow. Run vh lint before pushing to Git.

Fix warnings, not just errors: Warnings often point to configuration issues that will cause problems later.

---

What's Next?

• Generate YAML with valohai-utils to skip writing YAML by hand (Python users)

• Multiple YAML files for monorepo projects

• Managing large YAML files with anchors and aliases