{"record":{"id":"5856a684377185fa","repo":"nextcloud/all-in-one","slug":"could-not-start-container-identifier-details","errorCode":null,"errorMessage":"Could not start container {identifier}: {details}","messagePattern":"Could not start container (.+?): (.+?)","errorType":"exception","errorClass":"\\Exception","httpStatus":500,"severity":"critical","filePath":"php/src/Docker/DockerActionManager.php","lineNumber":202,"sourceCode":"            $response = substr($line, 8) . $separator;\n        }\n\n        while (($line = strtok($separator)) !== false) {\n            $response .= substr($line, 8) . $separator;\n        }\n\n        return $response;\n    }\n\n    public function StartContainer(Container $container, ?\\Closure $addToStreamingResponseBody = null): void {\n        $url = $this->BuildApiUrl(sprintf('containers/%s/start', urlencode($container->identifier)));\n        try {\n            if ($addToStreamingResponseBody !== null) {\n                $addToStreamingResponseBody(\"Starting container\", $container);\n            }\n            $this->sendHttpRequest('POST', $url);\n        } catch (RequestException $e) {\n            throw new \\Exception(\"Could not start container \" . $container->identifier . \": \" . $e->getResponse()?->getBody()->getContents());\n        }\n    }\n\n    public function CreateVolumes(Container $container): void {\n        $url = $this->BuildApiUrl('volumes/create');\n        foreach ($container->volumes->GetVolumes() as $volume) {\n            $forbiddenChars = [\n                '/',\n            ];\n\n            if ($volume->name === 'nextcloud_aio_nextcloud_datadir' || $volume->name === 'nextcloud_aio_backupdir') {\n                continue;\n            }\n\n            $firstChar = substr($volume->name, 0, 1);\n            if (!in_array($firstChar, $forbiddenChars)) {\n                $this->sendHttpRequest(\n                    'POST',","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/nextcloud/all-in-one/blob/6b788eec5e61733cf03ed380a3572e43ae3f11ce/php/src/Docker/DockerActionManager.php#L184-L220","documentation":"The Docker daemon answered POST /containers/{id}/start with an error (Guzzle RequestException carries the response) and the daemon's JSON error body is embedded as {details}. Note details can render empty when the failure occurred before any HTTP response existed. The start request performs port allocations, so daemon-level resource conflicts surface here.","triggerScenarios":"Container already running (409 'container already started'); host port allocation conflict with another process/container; storage or mount driver errors; SELinux/AppArmor denial; architecture-mismatched image failing to start.","commonSituations":"Re-running start on an already-running AIO container; another service binding the same host ports; full disk or missing mount targets; leftover containers from a failed update holding resources.","solutions":["Run docker logs and docker inspect on the failing container for the daemon's detailed reason","If the error is 'already started', treat it as success or stop the container first","Free conflicting host ports: ss -ltnp to find holders, stop the overlapping service/container","Check host disk space and mount targets, then retry the start"],"exampleFix":"// before: any RequestException is fatal\ntry { $docker->StartContainer($c); } catch (\\Exception $e) { throw $e; }\n// after: treat 'already started' (409) as success\nuse GuzzleHttp\\Exception\\RequestException;\ntry {\n    $docker->StartContainer($c);\n} catch (\\Exception $e) {\n    if (str_contains($e->getMessage(), 'already started')) { return; }\n    throw $e;\n}","handlingStrategy":"try-catch","validationCode":"// Skip the start call entirely when the container is already running\n$state = $docker->sendHttpRequest('GET', $docker->BuildApiUrl('containers/' . rawurlencode($id) . '/json'));\n$info = json_decode($state->getBody()->getContents(), true);\nif (($info['State']['Running'] ?? false) === true) {\n    return; // already started — POST would 409\n}","typeGuard":null,"tryCatchPattern":"try {\n    $docker->StartContainer($container);\n} catch (\\Exception $e) {\n    $msg = $e->getMessage();\n    if (str_contains($msg, 'already started')) { return; } // idempotent success\n    if (str_contains($msg, 'port is already allocated')) { freePortsOrReport($msg); return; }\n    throw $e;\n}","preventionTips":["Check State.Running via GET containers/{id}/json before issuing start — start is not idempotent","Reserve host ports exclusively per container to avoid allocation races","Always capture docker logs + daemon message body; empty details means no response existed (daemon socket issue)"],"tags":["php","docker","containers","daemon-api"],"backgroundTag":"docker-container-start-failed","analyzedSha":"6b788eec5e61733cf03ed380a3572e43ae3f11ce","analyzedAt":"2026-08-21T05:47:24.382Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}