multica-ai/multica · warning

--leader is required (agent name or ID)

Error message

--leader is required (agent name or ID)

What it means

Client-side flag validation in `multica squads create`: the `--leader` flag (agent name or agent ID that will lead the squad) is mandatory and was empty. Validated before any client construction or agent resolution, so no API traffic occurs. Distinct from later failures: if a non-empty leader cannot be resolved, you get a different `resolve leader` error from resolveAgent.

Source

Thrown at server/cmd/multica/cmd_squad.go:128

}

// ── Create ──────────────────────────────────────────────────────────────────

var squadCreateCmd = &cobra.Command{
	Use:   "create",
	Short: "Create a new squad",
	Args:  cobra.NoArgs,
	RunE:  runSquadCreate,
}

func runSquadCreate(cmd *cobra.Command, _ []string) error {
	name, _ := cmd.Flags().GetString("name")
	if name == "" {
		return fmt.Errorf("--name is required")
	}
	leader, _ := cmd.Flags().GetString("leader")
	if leader == "" {
		return fmt.Errorf("--leader is required (agent name or ID)")
	}

	client, err := newAPIClient(cmd)
	if err != nil {
		return err
	}
	ctx, cancel := cli.APIContext(context.Background())
	defer cancel()

	leaderID, err := resolveAgent(ctx, client, leader)
	if err != nil {
		return fmt.Errorf("resolve leader: %w", err)
	}

	body := map[string]any{
		"name":      name,
		"leader_id": leaderID,
	}

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Pass an existing agent's name or ID: `multica squads create --name x --leader agent-1`.
2. Verify the leader exists first: `multica agents list` — this also prevents the subsequent `resolve leader` error.
3. Fail fast on empty variables in scripts before invoking the CLI.

Example fix

# before
multica squads create --name "research squad"

# after
multica agents list > /dev/null   # confirm API access
multica squads create --name "research squad" --leader agent-1

: "${LEADER:?set LEADER to an agent name or ID}"
multica agents list --output json | jq -e --arg l "$LEADER" 'any(.[]; .name==$l or .id==$l)' > /dev/null \
  || { echo "leader agent not found: $LEADER"; exit 1; }
multica squads create --name "$SQUAD_NAME" --leader "$LEADER"

When it happens

Trigger: Running `multica squads create --name x` without --leader; empty LEADER variable in a script; leader value consisting only of whitespace.

Common situations: Automation provisioning squads before agents exist; unset env var in deployment config; user believes the server picks a default leader.

Related errors

• --name is required
• --cutoff is required; use the hosted deployment time of the
• --batch-size must be positive
• no fields to update; use --name, --description, --instructio
• --%s, --%s-stdin, and --%s-file are mutually exclusive; pick

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/7e4c7b886124c440. Report an issue: GitHub.