[docs] Add a "configuration errors" troubleshooting page
- Dominant language
- Python
- Stars
- 17.9k
- Forks
- 4.5k
- Avg merge
- 4d 6h
- Merged PRs (30d)
- 271
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
Research direction
Start by reading the current configuration validation code and existing CPU-only config-construction or unit tests to identify 5-8 stable failures. Draft the page in the user guide troubleshooting section with invalid and corrected configurations, searchable error excerpts, and explanations of each invariant. Done means every example is verified, uses current field names, excludes runtime CUDA/NCCL and performance topics, and the page is linked from troubleshooting.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, machine-learning
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100