<!--
{
  "documentType" : "article",
  "framework" : "Metal",
  "identifier" : "/documentation/Metal/command-buffer-debugging",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Command buffer debugging"
}
-->

# Command buffer debugging

Properties and methods for programmatically debugging runtime issues with a command buffer.

## Topics

### Identifying the command buffer

[`label`](/documentation/Metal/MTLCommandBuffer/label)

An optional name that can help you identify the command buffer.

[`commandQueue`](/documentation/Metal/MTLCommandBuffer/commandQueue)

The command queue that creates the command buffer.

[`device`](/documentation/Metal/MTLCommandBuffer/device)

The GPU device that indirectly owns the command buffer because you create it from a command queue the device also owns.

### Grouping commands within a GPU frame capture

[`pushDebugGroup(_:)`](/documentation/Metal/MTLCommandBuffer/pushDebugGroup(_:))

Marks the beginning of a debug group and gives it an identifying label, which temporarily replaces the previous group, if applicable.

[`popDebugGroup()`](/documentation/Metal/MTLCommandBuffer/popDebugGroup())

Marks the end of a debug group and, if applicable, restores the previous group from a stack.

### Getting error details

[`error`](/documentation/Metal/MTLCommandBuffer/error)

A description of an error when the GPU encounters an issue as it runs the command buffer.

[`errorOptions`](/documentation/Metal/MTLCommandBuffer/errorOptions)

Settings that determine which information the command buffer records about execution errors, and how it does it.

[`MTLCommandBufferEncoderInfo`](/documentation/Metal/MTLCommandBufferEncoderInfo)

A container that provides additional information about a runtime failure a GPU encounters as it runs the commands in a command buffer.

[`MTLCommandBufferEncoderInfoErrorKey`](/documentation/Metal/MTLCommandBufferEncoderInfoErrorKey)

A key to a command buffer error’s user information dictionary that retrieves additional information about a GPU’s runtime error.

### Reading the runtime message logs

[`logs`](/documentation/Metal/MTLCommandBuffer/logs-518l2)

The messages the command buffer records as the GPU runs its commands.

[`logs`](/documentation/Metal/MTLCommandBuffer/logs)

The messages the command buffer records as the GPU runs its commands.

### Checking scheduling times on the CPU

[`kernelStartTime`](/documentation/Metal/MTLCommandBuffer/kernelStartTime)

The host time, in seconds, when the CPU begins to schedule the command buffer.

[`kernelEndTime`](/documentation/Metal/MTLCommandBuffer/kernelEndTime)

The host time, in seconds, when the CPU finishes scheduling the command buffer.

### Checking execution times on the GPU

[`gpuStartTime`](/documentation/Metal/MTLCommandBuffer/gpuStartTime)

The host time, in seconds, when the GPU starts command buffer execution.

[`gpuEndTime`](/documentation/Metal/MTLCommandBuffer/gpuEndTime)

The host time, in seconds, when the GPU finishes execution of the command buffer.

### Determining whether to maintain strong references

[`retainedReferences`](/documentation/Metal/MTLCommandBuffer/retainedReferences)

A Boolean value that indicates whether the command buffer maintains strong references to the resources it uses.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)