docs(troubleshooting): offer shims for the Windows Path limit, and fix the test for it

[JamBalaya56562]

From #5830, where the reporter's Windows Path exceeds what cmd.exe accepts and npm/npx break. Three things in the "Path limits" section were worth fixing before anything structural is decided.

The documented test does not work

docs/troubleshooting.md tells you to run mise x -- cmd.exe /d /s /c "where.exe where" and shows it failing when Path is too long. It does not fail. where.exe is in C:\Windows\System32, which cmd.exe can still resolve while it is ignoring Path entirely.

Measured on Windows 11 26200 / cmd 10.0.26100.8875 — same Path for both columns, Git\cmd appended last:

Path length	where.exe where	git --version
2024	OK	OK
8129	OK	OK
8184	OK	OK
8349	OK	not recognized
12034	OK	not recognized
30019	OK	not recognized

The recommended probe reports success at every length, including where Path is being ignored outright. Anyone following the docs would conclude they were fine.

The limit is 8191, and it is not a truncation

The same measurement puts the cliff between 8184 and 8239 — the 8191 documented in KB 830473:

Even though the Win32 limitation for environment variables is 32,767 characters, Command Prompt ignores any environment variables that are inherited from the parent process and are longer than its own limitations of 8191 characters (as appropriate to the operating system).

That KB's "Applies to" only lists Windows 7 / Server 2008 R2 / 2012 R2, so it is worth stating that it still holds on current Windows 11 — the table above is that check.

Ignores, not truncates: past the limit nothing on Path resolves, so the symptom is every command reporting is not recognized, not one tool going missing. The old wording ("too long for certain tools to handle") suggests partial degradation.

Shims are now listed, along with what they do not cover

mise activate --shims keeps the shell's Path short — one directory instead of one per tool — and was missing from the list. It is listed now, but deliberately not as the fix, because it does not cover the failure this section is about.

Measured on v2026.8.0 with three tools active, this is the environment mise builds to run one of them:

$ mise x -- printenv PATH | tr ':' '\n' | grep installs
~/.local/share/mise/installs/jq/1.7
~/.local/share/mise/installs/shellcheck/0.10.0/shellcheck-v0.10.0
~/.local/share/mise/installs/shfmt/3.10.0

Every active tool, not just the one being run. So a shim hands npm the same long Path that activation would, and npm shelling out to cmd.exe fails identically. The entry states that scope rather than leaving readers to switch and find out.

Also noted

Duplicate entries are no longer part of this problem — #10162 (v2026.5.18) stopped install dirs re-accumulating on reactivation, and #11491 (v2026.7.18) collapses exact duplicates in computed environments. On the Path pasted in #5830 that is 208 entries / 8261 chars down to 125 / 4738. The section says so, and is explicit that it lowers mise's contribution without raising the ceiling.

Docs only — no code, no generated files.

Summary by CodeRabbit

• Documentation
  • Updated Windows PATH troubleshooting guidance to explain the cmd.exe 8,191-character limit and that oversized PATH values may be ignored entirely.
  • Improved diagnostic steps by recommending git, verifying the selected program exists, and avoiding system-directory or current-directory probes.
  • Documented PATH deduplication behavior, relevant version milestones, and shims as the first recommended mitigation, including their limitations.

[coderabbitai]

📝 Walkthrough

Walkthrough

The troubleshooting guide documents the Windows cmd.exe PATH limit, its failure behavior, shim-based mitigation, git diagnostics, and mise PATH deduplication.

Changes

Windows PATH troubleshooting

Layer / File(s)	Summary
PATH diagnostics and mitigation docs/troubleshooting.md	Documents the 8191-character limit and cmd.exe behavior. Adds shims as the first mitigation. Uses git resolution checks and explains PATH deduplication and probe selection.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• jdx/mise#11643: Addresses Windows cmd.exe PATH length detection and warning behavior related to this troubleshooting guidance.

Poem

A rabbit checks PATH in the morning light,
Keeps duplicate entries out of sight.
Git tests the route through every hop,
Shims lead the fix when PATH values stop.
At 8191 characters, cmd.exe stops.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the documentation changes for Windows PATH limits, shims, and the diagnostic test.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The troubleshooting documentation now accurately describes how an oversized Windows Path affects cmd.exe.

• Replaces the ineffective System32-based probe with a qualified git probe.
• Documents the System32 and current-directory resolution exceptions.
• Clarifies stale mise path cleanup, exact deduplication, and the limitations of shims as mitigation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/troubleshooting.md	Updates Windows Path-limit diagnosis and mitigation guidance; both previously reported documentation inaccuracies are corrected.

_{Reviews (3): Last reviewed commit: "docs(troubleshooting): correct the Windo..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/troubleshooting.md`:
- Around line 150-160: Update the troubleshooting example around the cmd.exe Git
probe to first verify that Git is installed and available through the normal
Path using git --version outside the cmd.exe invocation. If Git is unavailable,
instruct readers to substitute another known executable located outside
C:\Windows\System32, so the test distinguishes Path handling from a missing
installation.
- Line 137: Update the troubleshooting statement near the Path-length limit to
clarify that cmd.exe ignores an overlong inherited Path, so commands found only
through Path fail while directly resolvable System32 commands may still work;
retain the Microsoft documentation link and avoid claiming that every command
becomes unrecognized.
- Line 162: Revise the v2026.5.18 description in the troubleshooting
documentation to state that mise stopped retaining stale inherited install paths
during reactivation, while continuing to add install directories for the current
toolset. Preserve the separate v2026.7.18 exact-duplicate collapse statement and
the surrounding explanation about the 8191 limit.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 14612c7a-e9b8-4cf6-9301-b8d3017d169b

📥 Commits

Reviewing files that changed from the base of the PR and between e5230aa and 6641448.

📒 Files selected for processing (1)

• docs/troubleshooting.md

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/troubleshooting.md`:
- Line 160: Update the troubleshooting test guidance around the `where.exe`/`git
--version` probe to require an executable located outside both
`C:\Windows\System32` and the current working directory. Retain the precondition
that the executable runs normally and is available through `Path`, so a local
working-directory match cannot produce a false positive.
- Line 141: Update the shims guidance in the troubleshooting entry to scope its
benefit to preventing activation-time Path growth. Clarify that each shim still
invokes mise to construct the tool environment, so tools that launch child
processes such as cmd.exe may still inherit an overlong Path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 2fc64853-7309-4db0-8ead-7a455fd0e339

📥 Commits

Reviewing files that changed from the base of the PR and between 6641448 and c78c78b.

📒 Files selected for processing (1)

• docs/troubleshooting.md

Dismissed because a newer commit was pushed; Greptile will re-review the current head.