mathematic-inc/earl/troubleshoot-earl

Troubleshoot Earl

Cold-start diagnostic for when Earl isn't working. Follow the steps in order — each step may reveal the root cause.

What Agents Can Fix

• Earl not installed
• HCL parse errors
• Jinja render errors
• Template not found
• Wrong CLI flag order
• MCP config missing or incorrect
• SSRF blocks (suggest workaround)

What Requires Human Action

• Secret values — agent prints checklist; human runs earl secrets set <key> manually
• auth_code_pkce OAuth — agent provides command; human completes browser flow
• Agent restart for MCP — agent notes this; continues with CLI mode
• macOS keychain access dialog — agent warns; human clicks "Always Allow"

Step 1: Earl Doctor

earl doctor

If this fails with command not found: earl, Earl is not installed. Install it:

cargo install earl  # requires Rust toolchain + Node.js + pnpm
# or: curl -fsSL https://raw.githubusercontent.com/mathematic-inc/earl/main/scripts/install.sh | bash
# Windows: irm https://raw.githubusercontent.com/mathematic-inc/earl/main/scripts/install.ps1 | iex

If earl doctor reports other failures, address each one before continuing.

Step 2: Validate Templates

earl templates validate

Fix any errors found. Common errors and fixes:

Step 3: Check Template Exists

earl templates list

If the expected provider.command is not listed:

• Check that the file is in ./templates/ or the global template directory:

~/.config/earl/templates/ (macOS/Linux) or %APPDATA%\earl\templates\ (Windows)

• Check that provider in the HCL matches what you're calling (earl call <provider>.<command>)
• Re-run earl templates validate to catch parse errors

Step 4: Check Secrets

earl secrets list

If required secrets are missing, print the checklist:

Run in your terminal:
  earl secrets set <provider>.<key>
 
Tell me when done and I'll verify.

macOS note: If earl secrets set hangs for more than 5 seconds, check for a macOS system dialog behind your terminal window asking to allow Earl keychain access. Click "Always Allow."

After confirmation, re-run earl secrets list to verify keys are set.

Step 5: Check MCP Config (if using MCP)

Check that the MCP config file exists and contains the earl entry:

Claude Code: .claude/settings.json

{
  "mcpServers": {
    "earl": {
      "command": "earl",
      "args": ["mcp", "stdio"]
    }
  }
}

Note: ["mcp", "stdio", "--mode", "discovery"] is also valid — it is used when the template count is ≥ 30 (per setup-earl Phase 3). Do not remove the --mode discovery flag from a config that already has it; that would silently downgrade to full mode.

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), or ~/.config/Claude/claude_desktop_config.json (Linux)

Cursor: .cursor/mcp.json (project directory)

Windsurf: .windsurf/mcp.json (project directory)

If the config is missing or incorrect, write it (merging with existing entries, not overwriting).

MCP tools not visible? The config is correct but MCP tools only activate after restarting the agent. In the current session, use earl call --yes --json via Bash instead.

Step 6: Run the Failing Command

If all above pass, run the failing command directly and examine the output:

earl call --yes --json <provider>.<command> --<param> <value>

Match the error to the table:

Next Steps

• If the issue was a missing template: invoke create-template
• If the issue was MCP config: config is now written; restart your agent for MCP tools to activate
• If the issue required browser OAuth: run earl auth login <profile>, then retry the command
• If Earl still isn't working after all steps: run earl doctor --json and share the output