multica-ai/multica · error

invalid token format: must start with %s

Error message

invalid token format: must start with %s

What it means

During token login the CLI validates that the supplied personal access token starts with one of the recognized prefixes (mul_ or the cloud PAT prefix, per loginTokenPrefixes). Any other shape is rejected before a network call is made, so users get immediate feedback instead of an opaque 401.

Source

Thrown at server/cmd/multica/cmd_auth.go:41

)

// loginTokenPrefixes are the token prefixes `multica login --token` accepts.
// The CLI used to hardcode `mul_` only, which made it impossible to log in
// with a Multica Cloud Node PAT (`mcn_`) even though the server happily
// authenticates both kinds. Keep this list in sync with the prefix branches
// in server/internal/middleware/auth.go.
var loginTokenPrefixes = []string{"mul_", auth.CloudPATPrefix}

// validateLoginTokenPrefix returns nil if token starts with one of the
// CLI-recognised PAT prefixes, or an error describing the accepted set.
// Extracted so the prefix list has one obvious test surface.
func validateLoginTokenPrefix(token string) error {
	for _, p := range loginTokenPrefixes {
		if strings.HasPrefix(token, p) {
			return nil
		}
	}
	return fmt.Errorf("invalid token format: must start with %s", strings.Join(loginTokenPrefixes, " or "))
}

var authCmd = &cobra.Command{
	Use:   "auth",
	Short: "Authenticate multica with Multica",
}

var authStatusCmd = &cobra.Command{
	Use:   "status",
	Short: "Show current authentication status",
	RunE:  runAuthStatus,
}

var authLogoutCmd = &cobra.Command{
	Use:   "logout",
	Short: "Remove stored authentication token",
	RunE:  runAuthLogout,
}

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Re-copy the token from its source, ensuring the mul_ (or cloud PAT) prefix is included and no extra characters are selected
2. Paste into a text editor first to verify it is a single line with the correct prefix
3. If your token genuinely has another prefix, regenerate a PAT from the current product UI

Example fix

# before
multica login --token eyJhbGciOi...   # JWT, wrong shape

# after
multica login --token mul_ABCdef123...

# shell: check prefix before login
case "$MULTICA_TOKEN" in mul_*|"$(cloud prefix)"*) ;; *) echo 'token must start with mul_ or the cloud PAT prefix' >&2; exit 1;; esac
multica login --token "$MULTICA_TOKEN"

When it happens

Trigger: Passing `--token` with a JWT, a session cookie, a paste that lost its first characters, whitespace-merged text, or a token issued for a different auth system (e.g. an API key from another product).

Common situations: Copy-paste truncation (missing the mul_ prefix); pasting the token label/description instead of the value; using an OAuth id_token from browser sign-in instead of a PAT; tokens from an older server format.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• token is required
• agent execution context requires MULTICA_TOKEN to be a task-
• update user profile: %w
• create workspace: %w
• --cutoff is required; use the hosted deployment time of the

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