Billionmail/BillionMail · error

failed to create Docker client: %v

Error message

failed to create Docker client: %v

What it means

NewDockerAPI builds a Docker SDK client using client.FromEnv (DOCKER_HOST, certs, etc.) with API version negotiation. If the SDK cannot construct a client from the environment, construction fails with this wrapped error before any Docker call is attempted.

Source

Thrown at core/internal/service/dockerapi/dockerapi.go:34

	"time"

	"github.com/docker/docker/api/types/container"
	"github.com/docker/docker/api/types/filters"
	"github.com/docker/docker/client"
	"github.com/docker/docker/pkg/stdcopy"
)

// DockerAPI struct
type DockerAPI struct {
	client     *client.Client
	containers map[string]bool
}

// NewDockerAPI creates a new DockerAPI instance
func NewDockerAPI() (*DockerAPI, error) {
	cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
	if err != nil {
		return nil, fmt.Errorf("failed to create Docker client: %v", err)
	}

	return &DockerAPI{
		client:     cli,
		containers: make(map[string]bool),
	}, nil
}

// StartContainer starts a container
func (d *DockerAPI) StartContainer(ctx context.Context, containerID string) error {
	return d.client.ContainerStart(ctx, containerID, container.StartOptions{})
}

// StopContainer stops a container
func (d *DockerAPI) StopContainer(ctx context.Context, containerID string) error {
	timeout := gconv.Int(10 * time.Second)
	return d.client.ContainerStop(ctx, containerID, container.StopOptions{
		Timeout: &timeout,

View on GitHub (pinned to fc36c76c05)

Solutions

1. Check DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH env values are valid and files exist
2. Run `docker info` in the same environment to validate the Docker client config
3. Clear bogus DOCKER_* env vars so client.FromEnv falls back to the default unix socket
4. Inspect the wrapped cause (%v) for the exact option that failed (usually cert loading)

Example fix

// before
export DOCKER_HOST="192.168.1.5:2375" // malformed
// after
export DOCKER_HOST="tcp://192.168.1.5:2375"

if dh := os.Getenv("DOCKER_HOST"); dh != "" {
    if u, err := url.Parse(dh); err != nil || u.Scheme == "" {
        return fmt.Errorf("invalid DOCKER_HOST: %q", dh)
    }
}

api, err := dockerapi.NewDockerAPI()
if err != nil {
    if strings.Contains(err.Error(), "failed to create Docker client") {
        return fmt.Errorf("docker unavailable, check DOCKER_* env: %w", err)
    }
    return err
}

When it happens

Trigger: Invalid DOCKER_HOST URL format; bad TLS cert/key paths in DOCKER_CERT_PATH; a client.FromEnv option error such as unreadable certificates; in-process failures creating the HTTP client.

Common situations: DOCKER_HOST set to a malformed value (missing tcp:// or bad unix:// path); certificate files removed or permissions changed; running in an environment with a partially configured Docker context.

Related errors

• Read database password failed: %v
• failed to update BILLIONMAIL_HOSTNAME in .env file: %v
• environment file not found:
• failed to list containers: %w
• Failed to get configuration

AI-assisted analysis of Billionmail/BillionMail@fc36c76c05 (2026-09-05). Data as JSON: /api/errors/50aa93c17b5138df. Report an issue: GitHub.