---
title: Validating your app’s Metal API usage
framework: xcode
role: article
role_heading: Article
path: xcode/validating-your-apps-metal-api-usage
---

# Validating your app’s Metal API usage

Catch runtime issues in your Metal app using API Validation.

## Overview

Overview The API Validation layer checks for code that calls the Metal API incorrectly, including errors in creating resources, encoding Metal commands, and performing other common tasks. You can enable API Validation using the runtime diagnostics options in Xcode, or by using environment variables. important: The API Validation layer has a small, but measurable, impact on CPU performance. Enable API Validation in Xcode Follow these steps to enable API Validation using the runtime diagnostics options in the scheme settings: In the Xcode toolbar, choose Edit Scheme from the Scheme menu. Alternatively, choose Product > Scheme > Edit Scheme.  In the scheme action panel, select Run. In the action setting tab, click Diagnostics. Select API Validation to enable it, and click Close.  Now, Xcode enables API Validation each time you run your scheme. You can additionally use the Diagnostics tab to enable extra API Validation behaviors: Include load and store actions: You can enable this option to help debug incorrect load and store actions. It dynamically changes MTLLoadAction.dontCare to MTLLoadAction.clear to fuchsia color, and writes an alternating red and white checkerboard pattern into each render target with a store action of MTLStoreAction.dontCare. Use this option to debug incorrect load and store action modes or assumptions on the “don’t care” behavior. Log non-fatal actions: Enable additional logging of incorrect or suboptimal Metal usage that doesn’t prevent app execution. Use this option to further lint your Metal app. note: You can also control these options through environment variables. Enable API Validation with environment variables You can also enable API Validation by setting the following environment variables on your Metal app: For a complete list of settings, run man MetalValidation in Terminal. note: API Validation only checks unretained resource references from instances of MTLCommandBuffer and not from MTL4CommandBuffer.

## See Also

### Runtime diagnostics

- [Inspecting live resources at runtime](xcode/inspecting-live-resources-at-runtime.md)
- [Validating your app’s Metal shader usage](xcode/validating-your-apps-metal-shader-usage.md)
- [Monitoring your Metal app’s graphics performance](xcode/monitoring-your-metal-apps-graphics-performance.md)
- [Customizing the Metal Performance HUD](xcode/customizing-metal-performance-hud.md)
- [Understanding the Metal Performance HUD metrics](xcode/understanding-metal-performance-hud-metrics.md)
- [Gaining performance insights with the Metal Performance HUD](xcode/gaining-performance-insights-with-metal-performance-hud.md)
- [Generating performance reports with the Metal Performance HUD](xcode/generating-performance-reports-with-metal-performance-hud.md)