# Troubleshooting PyTorch - TPU

> [!WARNING]
> **Deprecated:** This page applies to PyTorch/XLA, which is deprecated and replaced by [TorchTPU](https://docs.cloud.google.com/tpu/docs/pytorch-on-tpu.md.txt). The PyTorch/XLA repo will be archived on November 15, 2026. Start new PyTorch workloads with TorchTPU and migrate existing PyTorch/XLA workloads to TorchTPU.

This guide provides troubleshooting information to
help you identify and resolve problems you might encounter while training
PyTorch models on Cloud TPU. For a more general guide to
getting started with Cloud TPU, see
[Quickstart: Create a TPU instance](https://docs.cloud.google.com/tpu/docs/quickstart-create-tpu-instance.md.txt).

> [!NOTE]
> **Note:** If you aren't able to resolve your issue using this guide, see [Getting Support](https://docs.cloud.google.com/tpu/docs/getting-support.md.txt) for further assistance.

## Troubleshooting slow training performance

If your model trains slowly, [generate and review a metrics report.](https://pytorch.org/xla/release/r2.6/learn/troubleshoot.html#get-a-metrics-report)

To automatically analyze the metrics report and provide a summary, run
your workload with PT_XLA_DEBUG=1.

For more information about issues that might cause your model to train slowly,
see [Known performance caveats](https://pytorch.org/xla/release/r2.6/learn/troubleshoot.html#known-performance-caveats).

## Performance profiling

To profile your workload in-depth to discover bottlenecks, review these resources:

- [PyTorch/XLA performance profiling](https://cloud.google.com/tpu/docs/pytorch-xla-performance-profiling-tpu-vm)
- [Sample MNIST training script with profiling](https://github.com/pytorch/xla/blob/master/test/test_profile_mp_mnist.py)

## More debugging tools

You can specify [environment variables](https://pytorch.org/xla/release/r2.6/learn/troubleshoot.html#environment-variables)
to control the behavior of the PyTorch/XLA software stack.

If you encounter an unexpected bug and need help, [file a GitHub issue](https://github.com/pytorch/xla).

## Managing XLA tensors

[XLA tensor Quirks](https://pytorch.org/xla/release/r2.6/learn/troubleshoot.html#xla-tensor-quirks)
describes what you should and shouldn't do when working with XLA tensors and
shared weights.