Malformed agent files cause API 500 errors instead of local parse errors

Summary

Agent files with invalid frontmatter (missing required name field) cause Claude Code to return API Error: 500 Internal server error on all subsequent API requests, instead of failing fast with a clear local parse error at startup.

Environment

• Claude Code: v2.1.29
• Platform: macOS (darwin)
• Install method: Homebrew

Root Cause

Two agent files in the project directory were missing the required name field in frontmatter:

/Users/hank/src/told/.claude/agents/effect-handler.md
/Users/hank/src/told/.claude/agents/verify-told.md

Example of invalid file (no YAML frontmatter):

# Effect Handler Expert

## Handler Template
...

Observed Behavior

1. Startup: Parse errors logged as DEBUG (not blocking)

From debug log at ~/.claude/debug/<session>.txt:

2026-02-03T15:41:03.958Z [DEBUG] Agent file /Users/hank/src/told/.claude/agents/effect-handler.md is missing required 'name' in frontmatter
2026-02-03T15:41:03.958Z [DEBUG] Failed to parse agent from /Users/hank/src/told/.claude/agents/effect-handler.md: Missing required "name" field in frontmatter
2026-02-03T15:41:03.958Z [DEBUG] Agent file /Users/hank/src/told/.claude/agents/verify-told.md is missing required 'name' in frontmatter
2026-02-03T15:41:03.958Z [DEBUG] Failed to parse agent from /Users/hank/src/told/.claude/agents/verify-told.md: Missing required "name" field in frontmatter

Startup continues normally - these are DEBUG level, not ERROR, and don't block.

2. User sends message: Immediate 500 error

From session file:

{
  "type": "assistant",
  "message": {
    "model": "<synthetic>",
    "content": [{"type": "text", "text": "API Error: 500 {\"type\":\"error\",\"error\":{\"type\":\"api_error\",\"message\":\"Internal server error\"},\"request_id\":\"req_011CXmPVnmSVWi5e4FtbmUKo\"}"}]
  },
  "error": "unknown",
  "isApiErrorMessage": true
}

Note: model: "<synthetic>" suggests the request may have failed before reaching the API, or the API rejected malformed input.

3. Error persists across sessions

Multiple new sessions all fail with 500 errors. Logging out and back in does not help.

4. Fix: Remove broken files + restart

rm /Users/hank/src/told/.claude/agents/effect-handler.md
rm /Users/hank/src/told/.claude/agents/verify-told.md

After restart, Claude Code works normally.

Expected Behavior

1. Fail fast: Invalid agent files should cause a clear error at startup:

``
Error: Failed to load agent file effect-handler.md
→ Missing required "name" field in frontmatter
→ Add frontmatter: ---\nname: "Agent Name"\n---
``

1. Don't proceed with broken state: If agent parsing fails, either:

• Block startup with actionable error
• Skip the invalid agent with a WARNING (not DEBUG) and continue
• Never send malformed data to the API

1. Correct error codes: If the error is local parsing, don't surface it as API Error: 500. Return appropriate local error.

Impact

• Hard blocker: User cannot use Claude Code at all until broken files are removed
• Misleading error: API Error: 500 with Anthropic request IDs suggests server-side issue
• Debugging cost: User spent time checking Anthropic status, re-authenticating, etc. instead of fixing local files
• Error is visible in /doctor but not correlated with the 500 errors

Additional Context

The /doctor command does show the agent parse errors:

Agent Parse Errors
└ Failed to parse 2 agent file(s):
  └ /Users/hank/src/told/.claude/agents/effect-handler.md: Missing required "name" field in frontmatter
  └ /Users/hank/src/told/.claude/agents/verify-told.md: Missing required "name" field in frontmatter

But this is only visible if user runs /doctor. The connection between these warnings and the 500 errors is not obvious.

Suggested Fix

1. Promote agent parse errors from DEBUG to WARNING or ERROR
2. Either fail startup or clearly warn that some agents are disabled
3. Ensure malformed agent data is never included in API requests
4. If local error, return local error message (not wrapped as API 500)