Enhancement: Detect bash hash conflicts and suggest `hash -r` on version check failure

Resolved 💬 3 comments Opened Oct 9, 2025 by gwpl Closed Jan 7, 2026

Summary

When Claude Code blocks execution due to outdated version, detect if bash's hash table is pointing to a different binary than PATH resolution, and suggest hash -r before asking to update.

Problem

Users with long-running bash sessions may have cached paths to old installations. After updating, which claude shows the new location, but bash still executes the cached old binary.

Symptom:

$ which claude
/home/user/.local/bin/claude

$ type claude
claude is hashed (/usr/local/bin/claude)  # Different location!

$ claude
# Shows "needs update" error despite having latest version

Fix: hash -r && claude

Why Add Detection?

  • Low cost: Simple check comparing executing binary with PATH resolution
  • High value: Catches issue at exact failure point
  • No harm: Only triggers when mismatch exists

Proposed Error Message

Your version needs an update to continue.

⚠️  Shell hash mismatch detected:
    Running:      /usr/local/bin/claude
    PATH finds:   /home/user/.local/bin/claude

Try clearing your shell's command cache first:
    hash -r && claude

If issue persists, update:
    claude update  # Will detect installation method and update appropriately

Real-World Error Output (for searchability)

<details>
<summary>Actual error users encounter</summary>

$ claude
╭────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code                      │
╰────────────────────────────────────────────────╯

It looks like your version of Claude Code needs an update.
A newer version is required to continue.

To update, please run:
    claude update

Diagnosis that would have helped:

$ type claude
claude is hashed (/old/path/claude)

$ which claude
/new/path/claude

# Solution:
$ hash -r

</details>

---

Common triggers: Multiple package managers, system + user installs, tmux/screen sessions created pre-update

Why not just document it? Users at the error state won't read docs first. Auto-detection at failure point = better UX.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗