Validate Your YAML (Linter)

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