invalid auth additional scopes, optional values are %v

Error message

invalid auth additional scopes, optional values are %v

What it means

One or more entries in auth.additionalScopes are not recognized. The validator uses lo.Every(SupportedAuthAdditionalScopes, c.AdditionalScopes), meaning every configured scope must be a member of the supported set (e.g. "HeartBeats", "NewWorkConns"). Unknown scopes abort client startup.

Source

Thrown at pkg/config/v1/validation/client.go:105

	}
	if !requirements.VirtualNet {
		for _, cfg := range visitorCfgs {
			if cfg.GetBaseConfig().Plugin.Type == v1.VisitorPluginVirtualNet {
				requirements.VirtualNet = true
				break
			}
		}
	}
	return requirements
}

func (v *ConfigValidator) validateAuthConfig(c *v1.AuthClientConfig) (Warning, error) {
	var errs error
	if !slices.Contains(SupportedAuthMethods, c.Method) {
		errs = AppendError(errs, fmt.Errorf("invalid auth method, optional values are %v", SupportedAuthMethods))
	}
	if !lo.Every(SupportedAuthAdditionalScopes, c.AdditionalScopes) {
		errs = AppendError(errs, fmt.Errorf("invalid auth additional scopes, optional values are %v", SupportedAuthAdditionalScopes))
	}

	errs = AppendError(errs, v.validateAuthTokenSource(c.Token, c.TokenSource))

	if err := v.validateOIDCConfig(&c.OIDC); err != nil {
		errs = AppendError(errs, err)
	}
	if c.Method == v1.AuthMethodOIDC && c.OIDC.TokenSource == nil {
		if err := ValidateOIDCClientCredentialsConfig(&c.OIDC); err != nil {
			errs = AppendError(errs, err)
		}
	}
	return nil, errs
}

func (v *ConfigValidator) validateOIDCConfig(c *v1.AuthOIDCClientConfig) error {
	if c.TokenSource == nil {
		return nil

View on GitHub (pinned to 6c8a8d0a97)

Solutions

Restrict auth.additionalScopes to values listed in the error message (subset of the supported set)
Remove the additionalScopes key if not needed
Confirm scope spelling/casing against the frp version in use

Example fix

# before
[auth]
method = "token"
token = "t"
additionalScopes = ["HeartBeats", "Metadata"]

# after
[auth]
method = "token"
token = "t"
additionalScopes = ["HeartBeats", "NewWorkConns"]

Defensive patterns

Strategy: validation

Validate before calling

func validScopes(scopes []string) bool {
    return lo.Every(validation.SupportedAuthAdditionalScopes, scopes)
}

Try / catch

if _, err := validation.ValidateClientCommonConfig(cfg); err != nil {
    if strings.Contains(err.Error(), "invalid auth additional scopes") {
        cfg.Auth.AdditionalScopes = nil // drop unsupported scopes, re-validate
    }
}

Prevention

Copy scope names from the frp docs of the exact version you deploy
Treat scopes as a fixed enum, not free-form

When it happens

Trigger: auth.additionalScopes contains a string not in SupportedAuthAdditionalScopes — e.g. "metadata", "user", or a scope name invented by analogy with other systems.

Common situations: Copy-pasting scope names from other auth systems; version drift where a scope was renamed; misunderstanding that scopes extend what the token authenticates (heartbeat/new-workconn messages), not generic RBAC.

Related errors

AI-assisted analysis of fatedier/frp@6c8a8d0a97 (2026-08-15). Data as JSON: /api/errors/e59752e73d6e5b0e. Report an issue: GitHub.