Plugin Version Mismatch Causes Silent Load Failure

Context

Date: 2026-02-02
Time Wasted: 5+ hours debugging across 3 devices
Severity: CRITICAL - plugins fail silently with NO error message
Impact: User sees "failed to load · 1 error" but NO details

Problem

Plugins failed to load with this unhelpful message:

contract-validator Plugin · leo-claude-mktplace · ✘ failed to load · 1 error

Claude Code provides NO error details. The user has to guess what's wrong.

Root Cause

Version mismatch between marketplace.json and plugin.json:

Plugin	marketplace.json	plugin.json	Status
contract-validator	1.2.0	1.1.0	FAILED
git-flow	1.2.0	1.0.0	FAILED
projman	3.4.0	3.3.0	FAILED
clarity-assist	1.2.0	1.0.0	FAILED
doc-guardian	1.1.0	1.0.0	FAILED

When Claude Code loads a plugin, it checks the version in marketplace.json and expects the same version in plugin.json. If they don't match, it silently fails.

How This Happened

Version was bumped in marketplace.json during releases
Individual plugin.json files were NOT updated
No validation caught the mismatch
Claude Code loaded plugins but failed silently

Solution

Fix all version mismatches:

# Check mismatches
python3 << 'EOF'
import json, os
with open('.claude-plugin/marketplace.json') as f:
    mkt = json.load(f)
mkt_ver = {p['name']: p['version'] for p in mkt['plugins']}
for p in os.listdir('plugins'):
    if os.path.exists(f'plugins/{p}/.claude-plugin/plugin.json'):
        with open(f'plugins/{p}/.claude-plugin/plugin.json') as f:
            pv = json.load(f)['version']
        if mkt_ver.get(p) != pv:
            print(f"MISMATCH: {p} mkt={mkt_ver[p]} plugin={pv}")
EOF

Clear corrupted cache:

rm -rf ~/.claude/plugins/cache/leo-claude-mktplace/{plugin-name}/

Restart Claude Code

Prevention

1. Add Version Sync Validation to Pre-Commit Hook

Add to scripts/validate-marketplace.sh:

# Validate version consistency
for plugin in plugins/*/; do
    name=$(basename "$plugin")
    mkt_ver=$(grep -A1 "\"$name\"" .claude-plugin/marketplace.json | grep version | grep -oE '[0-9.]+')
    plugin_ver=$(grep version "$plugin/.claude-plugin/plugin.json" | grep -oE '[0-9.]+')
    if [[ "$mkt_ver" != "$plugin_ver" ]]; then
        echo "ERROR: Version mismatch for $name"
        exit 1
    fi
done

2. Single Version Source

Consider using a script to update ALL version locations atomically.

3. Release Checklist

Update marketplace.json version
Update plugin.json version (MUST MATCH)
Run version consistency check
Clear plugin cache after update

Warning Signs

If you see this, check version consistency:

"✘ failed to load · 1 error" with no details
Plugin worked before, suddenly doesn't
After version bump, plugins stop loading

Claude Code provides no error details for plugin load failures
Cache can hold stale/orphaned versions
No built-in version consistency validation

Tags: version, plugin, silent-failure, cache, critical, marketplace, debugging