Billionmail/BillionMail · error

container with name %s not found

Error message

container with name %s not found

What it means

GetContainerByName lists Docker containers filtered by the given name and returns the first match. When the Docker list succeeds but returns zero containers, the name doesn't correspond to any existing container and this error is returned.

Source

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

	})
}

// GetContainerByName gets a container by its name
func (d *DockerAPI) GetContainerByName(ctx context.Context, name string) (*container.Summary, error) {
	args := filters.NewArgs()
	args.Add("name", name)

	containers, err := d.client.ContainerList(ctx, container.ListOptions{
		All:     true,
		Filters: args,
	})

	if err != nil {
		return nil, err
	}

	if len(containers) == 0 {
		return nil, fmt.Errorf("container with name %s not found", name)
	}

	return &containers[0], nil
}

// GetContainer gets container details
func (d *DockerAPI) GetContainer(ctx context.Context, containerID string) (container.InspectResponse, error) {
	return d.client.ContainerInspect(ctx, containerID)
}

// Close closes the Docker client connection
func (d *DockerAPI) Close() error {
	return d.client.Close()
}

// HostCommandResult stores the result of a command executed on the host
type HostCommandResult struct {
	ExitCode int    `json:"exit_code"` // Command exit status code

View on GitHub (pinned to fc36c76c05)

Solutions

1. Run `docker ps --format '{{.Names}}'` to list exact container names and correct the name argument
2. Start the target container (docker compose up -d) before calling the API
3. Docker name filters are anchors — pass the full exact name, not a substring or the compose service name alone
4. Recreate the container if it was renamed during a redeploy

Example fix

// before
api.ExecCommandByName("postfix") // service name, not container name
// after
api.ExecCommandByName("billionmail-postfix") // exact container name

func containerExists(ctx context.Context, cli *client.Client, name string) (bool, error) {
    cs, err := cli.ContainerList(ctx, container.ListOptions{All: true,
        Filters: filters.NewArgs(filters.Fany("name", name))})
    return len(cs) > 0, err
}

func hasContainer(r []*types.Container) bool { return len(r) > 0 }

out, err := api.ExecCommandByName(ctx, name, cmd)
if err != nil && strings.Contains(err.Error(), "not found") {
    log.Warnf("container %q missing, recreating...", name)
    return recreateContainer(name)
}

When it happens

Trigger: Calling GetContainerByName (directly or via RestartContainerByName / ExecCommandByName) with a name that has no exact matching container; container filters applied in the underlying list exclude it.

Common situations: Typo in container name; container was removed/recreated with a different name; calling before docker-compose up; confusing container name with service name or with the auto-generated compose name (project_service_1).

Related errors

• failed to list containers: %w
• failed to update BILLIONMAIL_HOSTNAME in postfix container:
• Failed to restart rspamd container: %v
• failed to hash postfix config: %v
• failed to restart postfix container: %v

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