What causes "MULTICA_SERVER_URL must use ws, wss, http, or https" in multica-ai/multica?

Use one of the four accepted schemes, e.g. MULTICA_SERVER_URL=https://multica.example.com or wss://multica.example.com

MULTICA_SERVER_URL must use ws, wss, http, or https

Error message

MULTICA_SERVER_URL must use ws, wss, http, or https

What it means

NormalizeServerBaseURL accepts only ws, wss, http, and https schemes; anything else (ftp, unix, file, empty scheme like 'localhost:8080' or 'example.com') reaches the default branch of the switch and returns this error. The normalizer's job is to convert a WebSocket URL into its HTTP base, so the scheme whitelist is the contract.

Source

Thrown at server/internal/daemon/config.go:588

		return false
	}
	return strings.EqualFold(u.Hostname(), officialCloudHost)
}

// NormalizeServerBaseURL converts a WebSocket or HTTP URL to a base HTTP URL.
func NormalizeServerBaseURL(raw string) (string, error) {
	u, err := url.Parse(strings.TrimSpace(raw))
	if err != nil {
		return "", fmt.Errorf("invalid MULTICA_SERVER_URL: %w", err)
	}
	switch u.Scheme {
	case "ws":
		u.Scheme = "http"
	case "wss":
		u.Scheme = "https"
	case "http", "https":
	default:
		return "", fmt.Errorf("MULTICA_SERVER_URL must use ws, wss, http, or https")
	}
	if u.Path == "/ws" {
		u.Path = ""
	}
	u.RawPath = ""
	u.RawQuery = ""
	u.Fragment = ""
	return strings.TrimRight(u.String(), "/"), nil
}

// TaskWorkspacesRootEnv carries the workspaces root of the daemon that owns a
// managed task into that task's environment. Task-mode `daemon disk-usage`
// reads this and nothing else: ResolveWorkspacesRoot derives its default from
// $HOME and the --profile name, so a task hosted by a named-profile daemon
// would otherwise scan the default root and silently report the wrong tree.
const TaskWorkspacesRootEnv = "MULTICA_TASK_WORKSPACES_ROOT"

// ResolveWorkspacesRoot returns the absolute path that the daemon and CLI

View on GitHub (pinned to 2c0912b6ec)

Solutions

Use one of the four accepted schemes, e.g. MULTICA_SERVER_URL=https://multica.example.com or wss://multica.example.com
If you typed a bare host, add the scheme — 'host' alone is interpreted as a path-less relative URL with empty scheme
Check for typos in the scheme (htps, htp, ws s) when the value was hand-edited

Example fix

# before (env)
export MULTICA_SERVER_URL=multica.example.com
# after
export MULTICA_SERVER_URL=https://multica.example.com

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(strings.TrimSpace(raw))
if err != nil {
    return fmt.Errorf("invalid MULTICA_SERVER_URL: %w", err)
}
switch u.Scheme {
case "ws", "wss", "http", "https":
    // ok
default:
    return fmt.Errorf("MULTICA_SERVER_URL %q must start with ws://, wss://, http://, or https://", raw)
}

Try / catch

Treat as a configuration error at startup: catch, show the accepted schemes plus the offending value, and exit before the daemon connects.

Prevention

Always write the scheme explicitly in config examples
Validate the scheme in config-lint tooling
Prefer https/wss in all documented snippets so users copy the right shape

When it happens

Trigger: Setting MULTICA_SERVER_URL without a scheme ('multica.example.com'), with a typo ('http//host' or 'htps://host'), or with an unsupported scheme ('unix:///run/multica.sock', 'ftp://...').

Common situations: Users writing hostnames without scheme, trailing-slash/typo mistakes, or attempts to point the daemon at a unix socket / custom transport that the client does not support.

Related errors

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