What causes "unknown trial subcommand: %s" in JuliusBrussee/caveman?

Check spelling against supported trial subcommands (e.g. promote).

unknown trial subcommand

Error message

unknown trial subcommand: %s

What it means

runTrial dispatches on the trial subcommand (e.g. promote); any unrecognized subcommand hits the default branch and exits with "unknown trial subcommand: %s" naming what was typed. This guards the trial command surface so typos fail fast with a clear message.

Solutions

Check spelling against supported trial subcommands (e.g. promote).
Run `caveman-proxy trial --help` or without a subcommand to list valid options.
Verify your caveman-proxy version supports the subcommand (upgrade if needed).
Use the exact subcommand name from docs; the CLI has no fuzzy matching.

Example fix

// before
caveman-proxy trial promte opt-42 --trial-id t-123
// after
caveman-proxy trial promote opt-42 --trial-id t-123

Defensive patterns

Strategy: validation

Validate before calling

valid := map[string]bool{"promote": true}
if !valid[sub] {
    return fmt.Errorf("unsupported trial subcommand %q; use promote", sub)
}

Try / catch

if out, err := cmd.Output(); err != nil && strings.Contains(string(out), "unknown trial subcommand") {
    // correct the subcommand name and retry
}

Prevention

Tab-complete or check --help instead of guessing subcommand names.
Pin your scripts to a caveman-proxy version whose subcommands you've verified.
Keep a thin wrapper script exposing only valid subcommands.

When it happens

Trigger: Running `caveman-proxy trial <word>` where <word> is not a recognized subcommand — e.g. `caveman-proxy trial list`, `promte`, or `export` if not implemented.

Common situations: Typos, guessing subcommand names, or using subcommands from a different caveman-proxy version (feature removed/renamed between releases).

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

		outDir := argFlag(args, "--out", filepath.Join(home, "exports", "trial-"+trialID))
		paths, err := spend.ExportTrial(plan, outDir)
		if err != nil {
			fatalJSON(logger, err)
		}
		printJSON(map[string]any{"trial_id": trialID, "export": paths})
	case "promote":
		trialID := requiredTrialID(logger, spend, args)
		optimizerID := firstPositional(args)
		if optimizerID == "" {
			fatalJSON(logger, fmt.Errorf("usage: caveman-proxy trial promote <optimizer_id> --trial-id <id>"))
		}
		plan, err := spend.BuildTrialPlan(trialID)
		if err != nil {
			fatalJSON(logger, err)
		}
		promoteMove(logger, home, trialID, optimizerID, plan)
	default:
		fatalJSON(logger, fmt.Errorf("unknown trial subcommand: %s", sub))
	}
}

func runUsage(logger *slog.Logger, args []string) {
	if len(args) == 0 {
		fatalJSON(logger, fmt.Errorf("usage: caveman-proxy usage import|link|refresh|unlink <provider>"))
	}
	sub := args[0]
	args = args[1:]
	home := mustHome(logger)
	spend := mustStore(logger, home)
	defer spend.Close()
	provider := firstPositional(args)
	switch sub {
	case "import":
		if provider == "" {
			fatalJSON(logger, fmt.Errorf("usage: caveman-proxy usage import codex|claude"))
		}

View on GitHub (pinned to 3ee70a1026)