> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/yaml/linter.md).

# YAML linter tool

The Cortex YAML linter validates your `cortex.yaml` files against both general YAML syntax and Cortex-specific schema requirements, catching invalid or incomplete entity definitions before they reach the platform.

This page covers the built-in tool available in the Cortex UI under **Tools > YAML Linter**. A separate linter is also built into the Cortex GitHub app, which runs checks on pull requests when you use GitHub in a [GitOps workflow](/configure/gitops.md).

## Using the YAML linter

### Validating a YAML file in the Cortex UI

1. From the main sidebar, expand **Tools**, then select **YAML linter**.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/8Csf7gbTKcJnPtAPQ0AW" alt="The YAML linter tool displayed in the Cortex UI." width="375"><figcaption></figcaption></figure></div>
2. Paste your YAML into the text editor, then click **Validate YAML**.
3. A status banner appears at the bottom of the page:
   * If the format is valid, a success message is displayed:

     <div align="left" data-with-frame="true"><figure><img src="/files/0UcjjVlYfTZF9KHBIXgA" alt="Valid YAML success icon and message."><figcaption></figcaption></figure></div>
   * If the format is incorrect:
     * For issues with the format of a Cortex-specific block, a warning banner appears:

       <div align="left" data-with-frame="true"><figure><img src="/files/PKCsd1r1G3ST1Ytagd2g" alt="The linter warning banner indicates that x-cortex-apm has an empty value in the YAML file."><figcaption></figcaption></figure></div>
     * For errors that cause the YAML to fail the linter check (such as missing a `title` or `x-cortex-tag`), a failure banner that includes the error message and which line is affected appears:

       <div align="left" data-with-frame="true"><figure><img src="/files/8RiohgjQ5tr9MB1uu8ht" alt="YAML fail icon and message."><figcaption></figcaption></figure></div>

### Validation scope

The linter checks for valid YAML structure and ensures required Cortex fields (like `openapi` version, `x-cortex-tag`, etc.) are present. If a required field is not present, this results in an error and the YAML does not pass the linter check.

The linter also validates the format of Cortex-specific blocks (e.g., `x-cortex-groups`, `x-cortex-firehydrant`) but does not verify the correctness of referenced data (such as whether a group or monitor ID actually exists). If there is an issue for a Cortex block, such as a block that doesn't contain a value, you will see a warning; however, the YAML will still pass the linter check.

If you submit a file with templating syntax (e.g., Jinja or cookiecutter variables like `{{ variable }}`), the linter will fail because these are not valid YAML until rendered. Only fully rendered YAML files will pass validation.

If the YAML is invalid or missing required fields, the linter will return errors indicating the line and nature of the problem.

### GitOps settings for the linter tool

If you are using GitHub in a GitOps workflow, you can adjust settings related to the linter. See [GitOps Settings](/configure/settings/gitops-settings.md) for more information.