Documented multi-GPU Docker command cannot run: ENTRYPOINT forgelm turns torchrun into an invalid subcommand (CR-A16-003) #409

Wave 1 · theme D1-5: Training, merging and export correctness · highest severity High · 1 finding(s) · effort small

Summary

Dockerfile:112 sets ENTRYPOINT ["forgelm"]. Docker appends docker run arguments to the ENTRYPOINT, so each documented multi-GPU invocation docker run --gpus all --shm-size=16g ... forgelm:full torchrun --nproc_per_node=4 -m forgelm.cli --config ... executes forgelm torchrun --nproc_per_node=4 .... Argparse rejects 'torchrun' as an invalid COMMAND and exits 2, which ForgeLM's exit-code contract labels a training failure, so CI would retry an infrastructure problem. The image also lacks DeepSpeed (see the preset finding), so of the two backends only FSDP could work even with --entrypoint torchrun.

Primary finding

CR-A16-003 — Documented multi-GPU Docker command cannot run: ENTRYPOINT forgelm turns torchrun into an invalid subcommand

severity High · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced (plumbing only) · already tracked: KNOWN-OPEN C31-DOCKER-RUNBOOK (DOCS-05+OPS-13) — docs/roadmap/phase-16-trust-surface-hardening.md:691-692

What happens. Dockerfile:112 sets ENTRYPOINT ["forgelm"]. Docker appends docker run arguments to the ENTRYPOINT, so each documented multi-GPU invocation docker run --gpus all --shm-size=16g ... forgelm:full torchrun --nproc_per_node=4 -m forgelm.cli --config ... executes forgelm torchrun --nproc_per_node=4 .... Argparse rejects 'torchrun' as an invalid COMMAND and exits 2, which ForgeLM's exit-code contract labels a training failure, so CI would retry an infrastructure problem. The image also lacks DeepSpeed (see the preset finding), so of the two backends only FSDP could work even with --entrypoint torchrun.

Where.

• Dockerfile:112-113
• docs/reference/distributed_training.md:193-201
• docs/guides/enterprise_deployment.md:53-62
• docs/reference/usage.md:388-389
• docs/reference/usage-tr.md:366-367
• docs/reference/distributed_training-tr.md:201-208
• docs/usermanuals/en/operations/docker.md:87
• docker-compose.yaml:48
• pyproject.toml:115-117

Evidence.

• Equivalent argv run in the snapshot lane: fpy -m forgelm torchrun --nproc_per_node=4 -m forgelm.cli --config /workspace/config.yaml gives exit=2 and "forgelm: error: argument COMMAND: invalid choice: 'torchrun' (choose from 'chat', 'export', ...)". fpy -m forgelm.cli --version works (exit 0), so the only problem is the entrypoint.

Recommended fix. Document docker run --entrypoint torchrun ... forgelm:full --nproc_per_node=4 -m forgelm.cli --config ... in the EN and TR guides, or teach the entrypoint a launcher mode. Add an INSTALL_DISTRIBUTED build arg.

Acceptance criteria

• A regression test reproduces the failure scenario and asserts the corrected behaviour.
• Documentation listed above is corrected in English and in its Turkish mirror in the same PR.
• Every finding in this issue is resolved or explicitly closed with a reason.

_{Found by the October 2026 ForgeLM code and documentation review against commit cab2947. Code links point at that commit; line numbers may have moved since. Finding IDs (CR-…, DOC-…, TECH-…) are stable references for this backlog.}