# 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](/cli-commands.md) and you're in a directory linked to a Valohai project.

Then run:

```shell
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:

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

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

### Missing required fields

Steps must have `name`, `image`, and `command`:

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

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

### Invalid parameter types

Parameters must specify a valid type:

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

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

### Syntax mistakes

Forgotten colons, quotes, or brackets:

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

```yaml
# ✅ 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:

```shell
$ 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](/valohai.yaml-overview/generate-from-python.md) to skip writing YAML by hand (Python users)
* [Multiple YAML files](/valohai.yaml-overview/multiple-files.md) for monorepo projects
* [Managing large YAML files](/valohai.yaml-overview/large-yaml.md) with anchors and aliases


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.valohai.com/valohai.yaml-overview/lint.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.