JuliusBrussee/caveman · error

unknown usage link source: %s

Error message

unknown usage link source: %s

What it means

Under `usage link`/`usage refresh`, the provider positional was not one of the accepted values (empty/claude, codex) and the dispatch hit the default arm, exiting 1. Empty provider is allowed here (defaults to claude), so this specifically means a non-empty unrecognized value.

Source

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

		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))
		}
	case "unlink":
		switch provider {
		case "claude", "anthropic":
			if err := spend.DeleteQuotaProvider("anthropic"); err != nil {
				fatalJSON(logger, err)
			}
			printJSON(map[string]any{"unlinked": "claude"})
		case "codex", "openai":
			if err := spend.DeleteQuotaProvider("openai"); err != nil {
				fatalJSON(logger, err)
			}
			printJSON(map[string]any{"unlinked": "codex"})
		default:
			fatalJSON(logger, fmt.Errorf("usage unlink needs claude|codex"))
		}
	default:
		fatalJSON(logger, fmt.Errorf("unknown usage subcommand: %s", sub))

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Use claude (or empty) or codex for link/refresh
2. Check `caveman-proxy usage link` output/docs for the supported set in your binary version
3. Filter your provider loop to the supported set before calling

Example fix

# before
for p in claude codex gemini vertex; do caveman-proxy usage link $p; done

# after
for p in claude codex; do caveman-proxy usage link $p; done

case "$PROVIDER" in ""|claude|codex) caveman-proxy usage link "$PROVIDER";; *) echo "unsupported link source: $PROVIDER" >&2;; esac

When it happens

Trigger: Running `caveman-proxy usage link gemini`, `usage refresh anthropic`, or any third provider name. Only claude and codex have refresh/import implementations in this build.

Common situations: New providers added to the proxy config but not to usage linking; scripts looping over all configured providers and hitting one without a usage source; alias confusion (anthropic works for unlink but not link).

Related errors

• unknown usage source: %s
• usage unlink needs claude|codex
• usage: caveman-proxy trial promote <optimizer_id> --trial-id
• unknown trial subcommand: %s
• usage: caveman-proxy usage import|link|refresh|unlink <provi

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/dea82e379548515a. Report an issue: GitHub.