What causes "unknown usage source: %s" in JuliusBrussee/caveman?

Use `codex` or `claude` exactly: `caveman-proxy usage import claude`.

unknown usage source

Error message

unknown usage source: %s

What it means

Thrown by runUsage's import branch: after the provider positional is present, it must be exactly `codex` or `claude`; the default case rejects anything else with `unknown usage source: <provider>`. The importer only has adapters for those two local session stores.

Solutions

Use `codex` or `claude` exactly: `caveman-proxy usage import claude`.
For `anthropic`, use `claude`; for `openai`, use `codex`.
To link/refresh quota for other providers use the `link` or `refresh` subcommands instead of `import`.

Example fix

// before
caveman-proxy usage import anthropic
// after
caveman-proxy usage import claude

Defensive patterns

Strategy: validation

Validate before calling

// shell
case "$PROVIDER" in claude|anthropic) PROVIDER=claude;; codex|openai) PROVIDER=codex;; *) echo "unsupported import source: $PROVIDER" >&2; exit 2;; esac
caveman-proxy usage import "$PROVIDER"

Prevention

Normalize aliases (anthropic→claude, openai→codex) in wrapper scripts.
Only codex and claude importers exist; route other providers to link/refresh.
Avoid free-form provider variables; hardcode the two valid values.

When it happens

Trigger: `caveman-proxy usage import gemini`, `usage import anthropic` (alias not accepted on import), `usage import openai`, or a typo like `usage import codex-cli`.

Common situations: Assuming `anthropic` works as an alias for `claude` (it does on `unlink` but not on `import`); trying to import usage for a provider with no importer (gemini/opencode/aider); typos in the provider name.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/1920b160562b6b8e. Report an issue: GitHub.

Appendix: source

Thrown at proxy/cmd/caveman-proxy/main.go:620

			fatalJSON(logger, fmt.Errorf("usage: caveman-proxy usage import codex|claude"))
		}
		path := argFlag(args, "--path", "")
		since := argFlag(args, "--since", "")
		switch provider {
		case "codex":
			out, err := spend.ImportCodex(path, since)
			if err != nil {
				fatalJSON(logger, err)
			}
			printJSON(out)
		case "claude":
			out, err := spend.ImportClaude(path, since)
			if err != nil {
				fatalJSON(logger, err)
			}
			printJSON(out)
		default:
			fatalJSON(logger, fmt.Errorf("unknown usage source: %s", provider))
		}
	case "link", "refresh":
		switch provider {
		case "", "claude":
			out, err := spend.RefreshClaudeUsageFromEnv()
			if err != nil {
				fatalJSON(logger, err)
			}
			printJSON(out)
		case "codex":
			out, err := spend.ImportCodex(argFlag(args, "--path", ""), argFlag(args, "--since", ""))
			if err != nil {
				fatalJSON(logger, err)
			}
			printJSON(out)
		default:
			fatalJSON(logger, fmt.Errorf("unknown usage link source: %s", provider))
		}

View on GitHub (pinned to 3ee70a1026)