vitessio/vitess · error

cannot load credentials from path template %s: %w

Error message

cannot load credentials from path template %s: %w

What it means

Same credential-template loading failure as the vtctldclient config, but in the vtadmin vtsql package: Parse renders `credentials-path-tmpl` and loads static gRPC auth credentials for the vtgate connection. Any template-render or file-read/parse error is wrapped with the template string and returned from Parse.

Source

Thrown at go/vt/vtadmin/vtsql/config.go:117

	effectiveUser := fs.String("effective-user", "", "username to send queries on behalf of")
	credentialsUsername := fs.String("credentials-username", "",
		"A string specifying the Username to use for authenticating with vtgate. "+
			"Used with credentials-password in place of credentials-path-tmpl, in cases where providing a static file cannot be done.")
	credentialsPassword := fs.String("credentials-password", "",
		"A string specifying a Password to use for authenticating with vtgate. "+
			"Used with credentials-username in place of credentials-path-tmpl, in cases where providing a static file cannot be done.")
	if err := fs.Parse(args); err != nil {
		return err
	}

	var username, password string

	// First load credentials from credentials-path-tmpl, if provided
	var tmplStrCreds *grpcclient.StaticAuthClientCreds
	if *credentialsTmplStr != "" {
		_creds, path, err := credentials.LoadFromTemplate(*credentialsTmplStr, c)
		if err != nil {
			return fmt.Errorf("cannot load credentials from path template %s: %w", *credentialsTmplStr, err)
		}

		c.CredentialsPath = path
		tmplStrCreds = _creds
	}
	if tmplStrCreds != nil {
		username = tmplStrCreds.Username
		password = tmplStrCreds.Password
	}

	// If credentials-username and credentials-password are provided, use those credentials instead
	if *credentialsUsername != "" {
		username = *credentialsUsername
	}
	if *credentialsPassword != "" {
		password = *credentialsPassword
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Manually render the template with the same config values and confirm the resulting file path exists and is readable.
2. Validate the credentials file format expected by grpcclient static auth (JSON user/password).
3. Fix field names in the template so they match exported fields of the vtsql config struct.
4. Use a literal credentials-path instead of the template variant if templating is not needed.

Example fix

// before
--credentials-path-tmpl "/etc/vtadmin/creds/{{.Cell}}"
// after (cell field not set in config)
--credentials-path "/etc/vtadmin/creds/zone1"

// Shell: verify the template renders to a readable file for the same config values
CREDS_PATH=$(render_template "$CREDS_TMPL")
test -r "$CREDS_PATH" || { echo "vtsql credentials not found at $CREDS_PATH"; exit 1; }

cfg, err := vtsql.ParseConfig(fs, flags, args); if err != nil && strings.Contains(err.Error(), "cannot load credentials") { /* check template fields and file */ }

When it happens

Trigger: Calling vtsql.ParseConfig with a non-empty credentials-path-tmpl when the template fails to render against the config struct, or the resolved credentials file is missing, unreadable, or malformed.

Common situations: Deployed vtadmin config references a template field that does not exist; credentials file permissions; Kubernetes secret not mounted; stale path after home-directory or cluster-name change.

Related errors

• cannot load credentials from path template %s: %w
• unregistered Authenticator implementation
• %w: no cluster with id %s
• error creating vtsql connection config: %w
• failed to execute tablet FQDN template for %+v: %w

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