Using Metal Validation

---
name: using-metal-validation
description: ALWAYS use when a user wants to enable, configure, or run Metal validation — API validation (MTL_DEBUG_LAYER) for CPU-side API misuse, shader validation (MTL_SHADER_VALIDATION) for GPU-side memory errors, or the load/store-action visual indicators. Trigger when working with Metal validation (MTL_DEBUG_LAYER, MTL_SHADER_VALIDATION, the validation layer, API validation, MTL_DEBUG_LAYER_VALIDATE_LOAD_ACTIONS, MTL_DEBUG_LAYER_VALIDATE_STORE_ACTIONS, per-pipeline validation, MTL4PipelineOptions.shaderValidation, validation perf hit), or when encountering symptoms like shader validation errors not appearing, fuchsia color render artifacts, the red/white checkerboard, or zerofill output. Do NOT trigger for general rendering bug diagnosis where validation isn't the relevant tool.
---

# Using Metal Validation

## Overview

Metal provides two validation modes, both configured via environment variables read at `MTLDevice` creation:

- **API validation** (`MTL_DEBUG_LAYER`) — CPU-side. Cheap; enable broadly during development.
- **Shader validation** (`MTL_SHADER_VALIDATION`) — GPU-side. Potentially significant perf cost; enable selectively or per-pipeline.

Env vars must be set **before** any `MTLDevice` is created. Changes after device creation have no effect.

## Step 1: Read the man page

The man page is the authoritative reference for all env vars, their valid mode values, and pipeline scoping syntax. Read it before configuring anything beyond the quick-start:

```sh
man MetalValidation | col -b
```

## Step 2: Quick-start