Troubleshooting

Adapted for this playbook from the 🤗 Transformers documentation by Hugging Face. Official page: https://huggingface.co/docs/transformers/troubleshooting. Images © Hugging Face (documentation-images) unless noted. This is not a substitute for the upstream docs — verify against the current version.

Covers Hugging Face pages: troubleshooting

Fast checks

1. Re-run the install smoke test from Installation
2. Confirm GPU visibility: nvidia-smi and torch.cuda.is_available()
3. Delete corrupted cache entries under ~/.cache/huggingface/hub for a specific repo if downloads break
4. Pin revision if a Hub update changed behaviour
5. Ensure tokenizer/pad_token is set for GPT-style generate calls

Common failure modes

Symptom	Likely cause
CUDA OOM	Batch/sequence too large; try dtype, PEFT, quantisation
trust_remote_code errors	Custom model requires review + flag
Gated repo 401/403	Missing login / licence acceptance
Nonsense generations	Wrong chat template or mixing tokenizers
Slow first call	Download + compile + CUDA warmup

Official page: Troubleshooting.

What to do next

API map or Flagship models.