1

lessons/patterns/plugin-load-errors---missing-name-field-in-command-frontmatter

Leo Miranda edited this page 2026-02-03 04:28:09 +00:00

Table of Contents

• Context
• Problem
• Root Cause
• Debugging Steps Taken (wasteful)
• Solution
• Prevention
• Time Wasted
• Filed Issue

Context

Plugin load failures showing only "1 error" with no details about what's wrong.

Problem

Claude Code's plugin loader doesn't surface specific validation errors. When a plugin fails to load, you see:

viz-platform Plugin · leo-claude-mktplace · ✘ failed to load · 1 error

No indication of WHAT the error is.

Root Cause

15 command markdown files were missing the required name: field in YAML frontmatter:

# WRONG - causes silent load failure
---
description: Some description
---

# CORRECT
---
name: command-name
description: Some description
---

Debugging Steps Taken (wasteful)

1. Checked MCP server venvs - OK
2. Checked symlinks - OK
3. Checked plugin.json files - OK
4. Checked hooks.json - OK
5. Checked run.sh scripts - OK
6. Finally checked command frontmatter - FOUND IT

Solution

Add name: field to all command files:

# Check for missing name fields
for f in plugins/*/commands/*.md; do
  grep -q '^name:' "$f" || echo "MISSING: $f"
done

Prevention

1. Validate before commit: Add pre-commit hook to check all command files have name: field
2. Template enforcement: Command file template must include name: as first field
3. File issue: Claude Code should show actual validation errors, not just "1 error"

Time Wasted

Significant token burn debugging every layer when error message should have said: "commands/chart.md: missing required 'name' field"

Filed Issue

GitHub issue template saved to .scratch/github-issue-plugin-errors.md for submission to anthropics/claude-code

---

Tags: plugins, debugging, frontmatter, claude-code, error-handling