What causes "invalid auth configuration file" in docker/cli?

Regenerate the entry with 'docker login' so it stores a correct base64('username:password-or-token').

invalid auth configuration file

Error message

invalid auth configuration file

What it means

Returned by decodeAuth after successfully base64-decoding the auth string: it splits the result on the first ':' to separate username and password. If there is no ':' (strings.Cut returns ok=false) or the username portion is empty, the auth entry is considered malformed. A valid auth credential must be 'username:secret'.

Solutions

Regenerate the entry with 'docker login' so it stores a correct base64('username:password-or-token').
Manually fix the value: echo -n 'username:token' | base64, then place the output in the 'auth' field.
Ensure the credential includes both a username and a colon separator before encoding.

Example fix

# before (broken - no colon)
auth: $(echo -n 'mytoken' | base64)
# after
auth: $(echo -n 'oauth2:mytoken' | base64)

Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate a base64 auth string decodes to user:secret before storing.
func validAuthB64(s string) error {
    dec, err := base64.StdEncoding.DecodeString(s)
    if err != nil { return err }
    if _, _, ok := strings.Cut(string(dec), ":"); !ok {
        return errors.New("decoded auth must be 'username:secret'")
    }
    return nil
}

Type guard

func isUserSecretAuth(b64 string) bool {
    dec, err := base64.StdEncoding.DecodeString(b64)
    if err != nil { return false }
    u, _, ok := strings.Cut(string(dec), ":")
    return ok && u != ""
}

Prevention

Always encode 'username:token', never a bare token.
Use 'docker login' to populate config.json correctly.
In CI, generate the value with printf '%s:%s' "$USER" "$TOKEN" | base64.

When it happens

Trigger: The 'auth' field in config.json (or in DOCKER_AUTH_CONFIG) base64-decodes to a string with no colon, or to ':password' (empty username). Hand-crafted base64 where someone encoded only a token, or encoded 'password' without a username.

Common situations: A user base64-encodes only an access token (no colon) when configuring registry auth. Migrating credentials from another tool that stores a bare token. Editing config.json and pasting a token directly instead of 'user:token'.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/92b0a3f53dbf5b50. Report an issue: GitHub.

Appendix: source

Thrown at cli/config/configfile/file.go:314

// decodeAuth decodes a base64 encoded string and returns username and password
func decodeAuth(authStr string) (string, string, error) {
	if authStr == "" {
		return "", "", nil
	}

	decLen := base64.StdEncoding.DecodedLen(len(authStr))
	decoded := make([]byte, decLen)
	authByte := []byte(authStr)
	n, err := base64.StdEncoding.Decode(decoded, authByte)
	if err != nil {
		return "", "", err
	}
	if n > decLen {
		return "", "", errors.New("something went wrong decoding auth config")
	}
	userName, password, ok := strings.Cut(string(decoded), ":")
	if !ok || userName == "" {
		return "", "", errors.New("invalid auth configuration file")
	}
	return userName, strings.Trim(password, "\x00"), nil
}

// GetCredentialsStore returns a new credentials store from the settings in the
// configuration file
func (c *ConfigFile) GetCredentialsStore(registryHostname string) credentials.Store {
	store := credentials.NewFileStore(c)

	if helper := getConfiguredCredentialStore(c, getAuthConfigKey(registryHostname)); helper != "" {
		store = newNativeStore(c, helper)
	}

	envConfig := os.Getenv(DockerEnvConfigKey)
	if envConfig == "" {
		return store
	}

View on GitHub (pinned to 4f84911bfe)