vitessio/vitess · error

failed to load static auth plugin. Plugin configured but grp

Error message

failed to load static auth plugin. Plugin configured but grpc-auth-static-password-file not provided

What it means

servenv's static gRPC auth plugin is registered because static auth was configured, but the required credential file flag grpc-auth-static-password-file is empty, so no authenticator can be constructed. The plugin initializer deliberately fails fast rather than starting an insecure server that appears auth-enabled.

Source

Thrown at go/vt/servenv/grpc_server_auth_static.go:136

}

// StaticAuthUsernameFromContext returns the username authenticated by the static auth plugin and stored in the Context, if any
func StaticAuthUsernameFromContext(ctx context.Context) string {
	username, ok := ctx.Value(staticAuthUsername).(string)
	if ok {
		return username
	}
	return ""
}

func newStaticAuthContext(ctx context.Context, username string) context.Context {
	return context.WithValue(ctx, staticAuthUsername, username)
}

func staticAuthPluginInitializer() (Authenticator, error) {
	entries := make([]StaticAuthConfigEntry, 0)
	if credsFile == "" {
		err := errors.New("failed to load static auth plugin. Plugin configured but grpc-auth-static-password-file not provided")
		return nil, err
	}

	data, err := os.ReadFile(credsFile)
	if err != nil {
		err := fmt.Errorf("failed to load static auth plugin %v", err)
		return nil, err
	}

	err = json.Unmarshal(data, &entries)
	if err != nil {
		err := fmt.Errorf("fail to load static auth plugin: %v", err)
		return nil, err
	}
	authEntries := make([]staticAuthEntry, 0, len(entries))
	for i, entry := range entries {
		authEntry := staticAuthEntry{StaticAuthConfigEntry: entry}
		if entry.CachingSha2Password != "" {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Pass --grpc-auth-static-password-file /path/to/creds.json whenever static auth is enabled
2. Verify the flag reaches the vttablet/vtctld process (check config templates and process args)
3. Ensure the file exists and is readable by the process user (next failure would be a read error)

Example fix

// before
vttablet --grpc-auth-static ... # no password file
// after
vttablet --grpc-auth-static --grpc-auth-static-password-file /etc/vitess/static_auth.json ...

if staticAuthEnabled && credsFile == "" {
    return errors.New("static auth enabled but --grpc-auth-static-password-file is not set")
}
if _, err := os.Stat(credsFile); err != nil {
    return fmt.Errorf("static auth file unreadable: %w", err)
}

When it happens

Trigger: Setting --grpc-auth-static (or otherwise registering the static plugin) without also supplying --grpc-auth-static-password-file; staticAuthPluginInitializer invoked at server startup with credsFile == "".

Common situations: Deployment configs enabling static auth but omitting the password-file flag; helm/env templating that drops the file path; the file flag applied to the wrong binary/process.

Related errors

• --batch-size requires 'direct' ddl_strategy
• --batch-size conflicts with --uuid-list. Batching does not s
• --batch-size only allowed when all queries are CREATE TABLE|
• missing value for 'rate'
• missing value for 'path'

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/138e842ed2c13c78. Report an issue: GitHub.