docs: explain why a checkpoint failed and how to fix it

[Hkhan161]

Summary

Customers hitting a checkpoint failure had nothing to read. Master already shipped a Performance guide for checkpointing (performance/checkpointing); this PR adds the failure-cause sections onto that page rather than introducing a duplicate.

Covers the three causes the checkpoint agent can name, with the fix for each:

• vLLM uses fork by default — set VLLM_WORKER_MULTIPROC_METHOD=spawn before vLLM is imported, or as an app secret when it is imported at module load.
• Open GPU file descriptors — prefer spawn for any process touching the GPU, don't init CUDA then fork.
• CUDA Unified Memory — cudaMallocManaged can't be checkpointed; use ordinary device allocations.
• Unknown cause — what to send support so we can classify it.

Also documents where the failure shows up (response body and the CEREBRIUM_CHECKPOINT_FAILED log line), and adds spawn to the existing vLLM example so the sample itself does not hit the most common failure.

The agent's error messages deep-link to these headings by anchor (#vllm-uses-fork-by-default, #open-gpu-file-descriptors, #cuda-unified-memory, #unknown-cause). Paired with CerebriumAI/cerebrium-checkpoint-agent#95 — merge this first so the links resolve.

Test plan

• mintlify dev renders /performance/checkpointing and the new sections appear
• Anchors resolve: #vllm-uses-fork-by-default, #open-gpu-file-descriptors, #cuda-unified-memory, #unknown-cause
• Relative link to /other-topics/using-secrets resolves

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cerebrium	🟢 Ready	View Preview	Aug 31, 2026, 3:35 PM