What causes "Could not create container {identifier}: {details}" in nextcloud/all-in-one?

Find the conflict: docker ps -a | grep , then docker rm the stale container and retry

nextcloud/all-in-one · critical · \Exception

Could not create container {identifier}: {details}

Error message

Could not create container {identifier}: {details}

What it means

POST /containers/create?name={identifier} returned an error; the daemon's message body is embedded. Typical daemon replies: 409 'Conflict. The container name "..." is already in use' (names are unique across running AND stopped containers) and 400 for invalid volume, port, or request-body specs.

Source

Thrown at php/src/Docker/DockerActionManager.php:517

        // Also DIUN should not send update notifications. See https://crazymax.dev/diun/providers/docker/#docker-labels
        // Also Dockhand should not be auto updating the containers. See https://dockhand.pro/manual/#container-labels-behavior
        // Additionally set a default org.label-schema.vendor and com.docker.compose.project
        $requestBody['Labels'] = ["com.centurylinklabs.watchtower.enable" => "false", "wud.watch" => "false", "diun.enable" => "false", "dockhand.update" => "false", "org.label-schema.vendor" => "Nextcloud", "com.docker.compose.project" => "nextcloud-aio"];

        // Containers should have a fixed host name. See https://github.com/nextcloud/all-in-one/discussions/6589
        $requestBody['Hostname'] = $container->identifier;

        $url = $this->BuildApiUrl('containers/create?name=' . $container->identifier);
        try {
            $this->sendHttpRequest(
                'POST',
                $url,
                [
                    'json' => $requestBody
                ]
            );
        } catch (RequestException $e) {
            throw new \Exception("Could not create container " . $container->identifier . ": " . $e->getResponse()?->getBody()->getContents());
        }

    }

    public function isRegistryReachable(Container $container): bool {
        $tag = $container->imageTag;
        if ($tag === '%AIO_CHANNEL%') {
            $tag = $this->GetCurrentChannel();
        }

        $remoteDigest = $this->GetLatestDigestOfTag($container->containerName, $tag);

        if ($remoteDigest === null) {
            return false;
        } else {
            return true;
        }
    }

View on GitHub (pinned to 6b788eec5e)

Solutions

Find the conflict: docker ps -a | grep <identifier>, then docker rm the stale container and retry
If ports conflict, stop the container holding them or change the bindings
Validate the request body (volumes, port mappings) against the Docker Engine API version in use
As a last resort clean up all AIO containers: docker rm -f $(docker ps -aq --filter name=nextcloud-aio)

Example fix

// before: create directly, fail on stale name
$docker->CreateContainer($container);
// after: remove a stopped stale container with the same name first
$existing = $docker->sendHttpRequest('GET', $docker->BuildApiUrl('containers/json?all=1'));
foreach (json_decode($existing->getBody(), true) as $c) {
    if (in_array('/' . $container->identifier, $c['Names'], true) && $c['State'] !== 'running') {
        $docker->sendHttpRequest('DELETE', $docker->BuildApiUrl('containers/' . $c['Id']));
    }
}
$docker->CreateContainer($container);

Defensive patterns

Strategy: validation

Validate before calling

// Detect and remove a stopped stale container with the same name before creating
$list = json_decode($docker->sendHttpRequest('GET', $docker->BuildApiUrl('containers/json?all=1'))->getBody(), true) ?: [];
foreach ($list as $c) {
    if (in_array('/' . $container->identifier, $c['Names'], true) && ($c['State'] ?? '') !== 'running') {
        $docker->sendHttpRequest('DELETE', $docker->BuildApiUrl('containers/' . $c['Id']));
    }
}

Try / catch

try {
    $docker->CreateContainer($container);
} catch (\Exception $e) {
    if (str_contains($e->getMessage(), 'name') && str_contains($e->getMessage(), 'already in use')) {
        removeStaleContainer($container->identifier);
        return $docker->CreateContainer($container); // exactly one recovery retry
    }
    throw $e;
}

Prevention

Container names are unique across running AND stopped containers — always remove-then-create in setup scripts
Delete (docker rm) before recreate; never assume a stopped container is harmless
Validate port mappings and volume names before sending the create request (400s come from bad specs)

When it happens

Trigger: A container with the same name already exists (running or stopped/exited); duplicate host-port bindings in the request; a referenced volume, network, or image that is invalid or missing.

Common situations: Re-running AIO setup without removing the previous container; stale containers left after a failed update; editing a container's config while the old one still exists.

Related errors

AI-assisted analysis of nextcloud/all-in-one@6b788eec5e (2026-08-21). Data as JSON: /api/errors/b3bc4bea7df2c1bb. Report an issue: GitHub.