unknown token format - expecting "file://" or "token:" prefi

Error message

unknown token format - expecting "file://" or "token:" prefix

What it means

With the token auth plugin selected, authParams must use either the "file://" prefix (token read from a file) or the "token:" prefix (inline token). Any other format hits the default case and returns this error, stopping the instance.

Source

Thrown at pulsar-function-go/pf/instance.go:226

	clientOpts := pulsar.ClientOptions{
		URL:                        ic.pulsarServiceURL,
		TLSTrustCertsFilePath:      ic.tlsTrustCertsPath,
		TLSAllowInsecureConnection: ic.tlsAllowInsecure,
		TLSValidateHostname:        ic.tlsHostnameVerification,
	}

	switch ic.authPlugin {
	case authPluginToken:
		switch {
		case strings.HasPrefix(ic.authParams, "file://"):
			clientOpts.Authentication = pulsar.NewAuthenticationTokenFromFile(ic.authParams[7:])
		case strings.HasPrefix(ic.authParams, "token:"):
			clientOpts.Authentication = pulsar.NewAuthenticationToken(ic.authParams[6:])
		case ic.authParams == "":
			return fmt.Errorf("auth plugin %s given, but authParams is empty", authPluginToken)
		default:
			return fmt.Errorf(`unknown token format - expecting "file://" or "token:" prefix`)
		}
	case authPluginNone:
		clientOpts.Authentication, _ = pulsar.NewAuthentication("", "") // ret: auth.NewAuthDisabled()
	default:
		return fmt.Errorf("unknown auth provider: %s", ic.authPlugin)
	}

	client, err := pulsar.NewClient(clientOpts)
	if err != nil {
		log.Errorf("create client error:%v", err)
		gi.stats.incrTotalSysExceptions(err)
		return err
	}
	gi.client = client
	return nil
}

func (gi *goInstance) setupProducer() error {

View on GitHub (pinned to 820761864e)

Solutions

Prefix inline tokens: authParams = "token:" + jwt.
Prefix file paths exactly: authParams = "file:///etc/pulsar/token".
If you don't need auth, switch AuthenticationPlugin to the none plugin instead.

Example fix

// before
--auth_params "eyJhbGciOi..." // unknown token format
// after
--auth_params "token:eyJhbGciOi..."

Defensive patterns

Strategy: validation

Validate before calling

if authParams != "" && !strings.HasPrefix(authParams, "file://") && !strings.HasPrefix(authParams, "token:") {
    return fmt.Errorf("authParams must start with file:// or token:")
}

Try / catch

if err := runInstance(); err != nil && strings.Contains(err.Error(), "unknown token format") {
    log.Fatalf(`fix authParams: use "token:<jwt>" or "file:///path"`)
}

Prevention

Always build authParams as "token:"+jwt or "file://"+absPath in deploy tooling.
Note the prefix is case-sensitive and lowercase.
Document the expected format next to the function config template.

When it happens

Trigger: authParams set to a raw JWT without the "token:" prefix, or a path without the "file://" prefix, or any other arbitrary string while the token plugin is enabled.

Common situations: Copy-pasting a JWT directly into auth params; using "File://" or "file:/" wrong casing/spelling; mixing up param formats from a different auth plugin.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/38009150a54eb87f. Report an issue: GitHub.