multica-ai/multica · error

--app-url is required when --server-url points at a remote h

Error message

--app-url is required when --server-url points at a remote host (e.g. --app-url https://app.internal.co)

What it means

Validation error from `multica setup self-host`: --app-url was omitted, --server-url was user-provided and points at a remote (non-local) host, and the interactive prompt either could not be shown or the user entered nothing. The CLI refuses to guess the frontend URL because api.x.co vs app.x.co or an https front-end cannot be derived reliably; a wrong guess would produce a broken login URL.

Source

Thrown at server/cmd/multica/cmd_setup.go:214

	// Before this, setup self-host read only the flags, so a self-hoster who set
	// MULTICA_SERVER_URL still got the localhost default and an "unreachable"
	// error (GitHub #3912).
	existing, _ := cli.LoadCLIConfigForProfile(profile)
	serverURL, userProvidedServerURL := resolveSelfHostServerURL(cmd, existing)
	appURL := resolveSelfHostAppURL(cmd, existing)
	frontendPort, _ := cmd.Flags().GetInt("frontend-port")

	if appURL == "" {
		if userProvidedServerURL && !serverHostIsLocal(serverURL) {
			// We can't guess the frontend URL for a remote server: api.x.co
			// and app.x.co, or an https-fronted deployment, would silently
			// produce a broken login URL. Ask the user instead.
			entered, err := promptAppURL(serverURL)
			if err != nil {
				return err
			}
			if entered == "" {
				return fmt.Errorf("--app-url is required when --server-url points at a remote host (e.g. --app-url https://app.internal.co)")
			}
			appURL = entered
		} else {
			appURL = fmt.Sprintf("http://localhost:%d", frontendPort)
		}
	}

	ok, err := confirmOverwrite(profile, serverURL, appURL)
	if err != nil {
		return err
	}
	if !ok {
		return nil
	}

	// Probe before persisting anything. A failed setup must never overwrite a
	// working config or wipe the saved token: persistSelfHostConfigIfReachable
	// writes only when the server answers, so an unreachable host leaves the

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Pass the frontend URL explicitly: `multica setup self-host --server-url https://api.internal.co --app-url https://app.internal.co`.
2. If running interactively, re-run the command and enter the app URL at the prompt instead of leaving it blank.
3. For scripted runs, always include --app-url because the prompt is not available without a TTY.
4. Double-check the value answers at the browser-facing origin (where the login page opens), not the API origin.

Example fix

# before
multica setup self-host --server-url https://api.internal.co
# after
multica setup self-host --server-url https://api.internal.co --app-url https://app.internal.co

# Shell: refuse to run remote self-host setup without an app URL
server_host="$(printf '%s' "$SERVER_URL" | sed -E 's#https?://([^/:]+).*#\1#')"
case "$server_host" in localhost|127.*|::1) ;; *) [ -n "$APP_URL" ] || { echo "APP_URL required for remote server"; exit 2; } ;; esac

Detect the '--app-url is required' message in the command's stderr and fail the automation job early with a clear missing-parameter error rather than retrying.

When it happens

Trigger: Running `multica setup self-host --server-url https://api.internal.co` without --app-url in a non-interactive terminal (CI, pipe, script) where promptAppURL returns an empty string, or answering the prompt with empty input.

Common situations: Automating setup in a provisioning script without passing --app-url; SSH sessions without a TTY; users assuming the app URL is derived from the server URL like in earlier versions.

Related errors

• invalid direction %q (want \"up\" or \"down\")
• --name is required
• --runtime-id is required
• --runtime-config must be valid JSON: %w
• %s must be a JSON object, or 'null' to clear

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