docker/cli · error

resolving credentials failed

Error message

resolving credentials failed: %w

What it means

Returned by createContainer() when --use-api-socket is active, DOCKER_CONFIG is not already injected, and readCredentials(dockerCLI) fails (cli/command/container/create.go:299-302). readCredentials itself returns either the DOCKER_AUTH_CONFIG parse error (271) or the GetAllCredentials store error (272); this wrapper re-wraps either as 'resolving credentials failed' so that credential problems fail fast before the container is created.

Solutions

1. Fix DOCKER_AUTH_CONFIG JSON formatting (see error 271).
2. Ensure the configured credential helper is installed and functional (see error 272).
3. If you inject DOCKER_CONFIG yourself into the container env, the credential-resolution step is skipped.
4. Drop --use-api-socket if you do not need the container to authenticate to the Docker API.

Example fix

# before
docker run --use-api-socket ...   # DOCKER_AUTH_CONFIG malformed -> resolve fails
# after
export DOCKER_AUTH_CONFIG='{"auths":{"registry.example.com":{"auth":"<base64>"}}}'
docker run --use-api-socket ...

// Resolve credentials explicitly before using --use-api-socket.
func validateCredsForApiSocket(p config.Provider) error {
    if _, err := container.ReadCredentials(p); err != nil {
        return fmt.Errorf("fix DOCKER_AUTH_CONFIG or credential helper before --use-api-socket: %w", err)
    }
    return nil
}

if _, err := createContainer(ctx, cli, cfg, opts); err != nil {
    if strings.Contains(err.Error(), "resolving credentials failed") {
        // hint: validate DOCKER_AUTH_CONFIG JSON / credential helper, or drop --use-api-socket
    }
}

When it happens

Trigger: Running docker create/run with --use-api-socket, where DOCKER_AUTH_CONFIG is malformed (see 271) or the local credential store/helper cannot be read (see 272). The credential resolution is performed early so the container is not created with a broken API-socket credential setup.

Common situations: Using --use-api-socket to give a container access to the Docker API with the caller's credentials, but those credentials cannot be resolved due to a malformed DOCKER_AUTH_CONFIG or a broken credsStore helper.

Related errors

• failed to read credentials from DOCKER_AUTH_CONFIG
• resolving credentials failed
• saving creds
• error establishing connection to trust repository
• failed to parse hook template

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

Appendix: source

Thrown at cli/command/container/create.go:301

		           Mode:      0o600,
		       },
		   })
		*/

		var envVarPresent bool
		for _, envVar := range containerCfg.Config.Env {
			if strings.HasPrefix(envVar, "DOCKER_CONFIG=") {
				envVarPresent = true
			}
		}

		// If the DOCKER_CONFIG env var is already present, we assume the client knows
		// what they're doing and don't inject the creds.
		if !envVarPresent {
			// Resolve this here for later, ensuring we error our before we create the container.
			creds, err := readCredentials(dockerCLI)
			if err != nil {
				return "", fmt.Errorf("resolving credentials failed: %w", err)
			}
			if len(creds) > 0 {
				// Set our special little location for the config file.
				containerCfg.Config.Env = append(containerCfg.Config.Env, "DOCKER_CONFIG="+path.Dir(dockerConfigPathInContainer))

				apiSocketCreds = creds // inject these after container creation.
			}
		}
	}

	var platform *ocispec.Platform
	if options.platform != "" {
		p, err := platforms.Parse(options.platform)
		if err != nil {
			return "", invalidParameter(fmt.Errorf("error parsing specified platform: %w", err))
		}
		platform = &p
	}

View on GitHub (pinned to 4f84911bfe)