NVIDIA/Megatron-LM

[docs] Add a "configuration errors" troubleshooting page

Open

#5,766 opened on Jul 12, 2026

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Python (1,723 forks)batch import
documentationgood first issue

Repository metrics

Stars
 (7,565 stars)
PR merge metrics
 (Avg merge 12d 9h) (245 merged PRs in 30d)

Description

Description Megatron Core validates many interactions between tensor, pipeline, context, expert, and sequence parallelism. The resulting errors are useful individually, but users lack a central explanation of how to diagnose them. Add a short troubleshooting page covering 5-8 common validation failures already present in current code. For each:

  • Show a minimal invalid configuration.
  • Include the relevant error text or a stable excerpt.
  • Explain the violated invariant.
  • Show one corrected configuration.

Candidate topics include divisibility requirements, parallel-size relationships, virtual pipeline configuration, and incompatible precision options.

Do not document runtime CUDA/NCCL failures or performance tuning in this issue.

Acceptance criteria

  • Every example is verified by a CPU-only config-construction test or existing unit test.
  • Examples use current configuration field names.
  • Error excerpts are specific enough to search for but do not depend on line numbers.
  • The page is linked from the user guide troubleshooting section.

Contributor guide