workspace ID is required to resolve agents; use --workspace-

Error message

workspace ID is required to resolve agents; use --workspace-id or set MULTICA_WORKSPACE_ID

What it means

resolveAgent accepts a bare agent name only when it can scope the lookup to a workspace (GET /api/agents?workspace_id=...). If the argument is not a canonical UUID (uuidRegexp) and client.WorkspaceID is empty, name resolution is impossible and the CLI refuses rather than searching across workspaces.

Source

Thrown at server/cmd/multica/cmd_autopilot.go:782

	}
	return inputs, nil
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

// uuidRegexp matches a canonical UUID (8-4-4-4-12 hex).
var uuidRegexp = regexp.MustCompile(`^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`)

// resolveAgent accepts either a UUID or an agent name (case-insensitive substring)
// and returns the agent's UUID. Errors on no match or ambiguous match.
func resolveAgent(ctx context.Context, client *cli.APIClient, nameOrID string) (string, error) {
	if uuidRegexp.MatchString(nameOrID) {
		return nameOrID, nil
	}
	if client.WorkspaceID == "" {
		return "", fmt.Errorf("workspace ID is required to resolve agents; use --workspace-id or set MULTICA_WORKSPACE_ID")
	}

	var agents []map[string]any
	agentPath := "/api/agents?" + url.Values{"workspace_id": {client.WorkspaceID}}.Encode()
	if err := client.GetJSON(ctx, agentPath, &agents); err != nil {
		return "", fmt.Errorf("fetch agents: %w", err)
	}

	nameLower := strings.ToLower(nameOrID)
	type match struct{ ID, Name string }
	var matches []match
	for _, a := range agents {
		aName := strVal(a, "name")
		if strings.Contains(strings.ToLower(aName), nameLower) {
			matches = append(matches, match{ID: strVal(a, "id"), Name: aName})
		}
	}

View on GitHub (pinned to 2c0912b6ec)

Solutions

Pass --workspace-id <uuid> on the command.
Or export MULTICA_WORKSPACE_ID=<uuid> (persist in shell profile / CI secrets).
Or use the agent's full UUID as the --agent value, which bypasses workspace-scoped lookup entirely.

Example fix

# before
multica autopilot trigger create --name t1 --agent triage-bot
# after
MULTICA_WORKSPACE_ID=ws-uuid multica autopilot trigger create --name t1 --agent triage-bot

Defensive patterns

Strategy: validation

Validate before calling

# ensure a workspace is always in scope
: "${MULTICA_WORKSPACE_ID:?set MULTICA_WORKSPACE_ID or pass --workspace-id}"
multica autopilot trigger create --name t1 --agent triage-bot

Prevention

Export MULTICA_WORKSPACE_ID in shell profile and CI environment.
Cache agent UUIDs in scripts; UUIDs skip workspace-scoped name resolution entirely.

When it happens

Trigger: Running an autopilot command with an agent name (not UUID) while --workspace-id is omitted and MULTICA_WORKSPACE_ID is unset, e.g. `multica autopilot trigger create --agent triage-bot` in a fresh shell.

Common situations: New machine or CI environment without the env var persisted; switching workspaces and the cached config cleared; scripting that assumes the workspace is implicit.

Related errors

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