server URL not set: use --server-url flag, MULTICA_SERVER_UR

Error message

server URL not set: use --server-url flag, MULTICA_SERVER_URL env, or 'multica config set server_url <url>'

What it means

newAPIClient could not determine the Multica server URL: the --server-url flag is unset, MULTICA_SERVER_URL is empty, and no server_url was persisted via `multica config set`. The message lists all three remedies explicitly.

Source

Thrown at server/cmd/multica/cmd_agent.go:273

	taskContext := inDaemonManagedExecutionContext()
	token := resolveToken(cmd)
	if taskContext && !strings.HasPrefix(token, "mat_") {
		// When the ONLY daemon signal is a workdir marker (no MULTICA_AGENT_ID /
		// MULTICA_TASK_ID / MULTICA_DAEMON_PORT), the likeliest cause outside a
		// real task is a leftover marker from a crashed daemon task in a
		// local_directory. Name the exact file so a normal user can recover
		// instead of hitting an opaque "requires mat_ token" error. Shares its
		// wording with requireHumanLocalCommand: same cause, same remedy.
		if markerPath := leftoverDaemonTaskMarkerPath(); markerPath != "" {
			return nil, fmt.Errorf("agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token%s", leftoverMarkerSuffix(markerPath))
		}
		return nil, fmt.Errorf("agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token%s", daemonPortOnlyContextHint())
	}

	serverURL := resolveServerURL(cmd)
	workspaceID := resolveWorkspaceID(cmd)
	if serverURL == "" {
		return nil, fmt.Errorf("server URL not set: use --server-url flag, MULTICA_SERVER_URL env, or 'multica config set server_url <url>'")
	}

	client := cli.NewAPIClient(serverURL, workspaceID, token)
	// When running inside a daemon task, attribute actions to the agent.
	if agentID := os.Getenv("MULTICA_AGENT_ID"); agentID != "" {
		client.AgentID = agentID
	}
	if taskID := os.Getenv("MULTICA_TASK_ID"); taskID != "" {
		client.TaskID = taskID
	}
	return client, nil
}

const (
	defaultCloudServerURL = "https://api.multica.ai"
	defaultCloudAppURL    = "https://multica.ai"
)

View on GitHub (pinned to 2c0912b6ec)

Solutions

Set the env var for one-off use: MULTICA_SERVER_URL=https://app.multica.dev multica agent list.
Persist it: multica config set server_url https://app.multica.dev.
Pass --server-url on the command when mixing multiple environments.
If in a daemon task, verify the task-local config root is populated rather than an empty injected directory.

Example fix

# before
multica agent list  # -> server URL not set

# after
multica config set server_url https://app.multica.dev
multica agent list

Defensive patterns

Strategy: validation

Validate before calling

serverURL := resolveServerURL(cmd)
if serverURL == "" {
    return fmt.Errorf("server URL not set: use --server-url flag, MULTICA_SERVER_URL env, or 'multica config set server_url <url>'")
}

Prevention

Run `multica config set server_url <url>` as part of workstation setup.
In scripts and containers, always export MULTICA_SERVER_URL explicitly.
Add a preflight check that errors with the three supported remedies before doing real work.

When it happens

Trigger: Fresh install where no config was ever written; a CI/container environment that sets only the token and workspace but not the URL; a profile whose config file lacks server_url; the MULTICA_SERVER_URL var misspelled.

Common situations: First run after install; switching machines or profiles; scripts that assume config carries over; running inside a daemon task where the task-local config root is a fresh, empty directory.

Related errors

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