{"record":{"id":"83a7409c34b6aac2","repo":"floci-io/floci","slug":"shared-volume-init-for-volumename-exited-with-s","errorCode":null,"errorMessage":"shared-volume init for ${volumeName} exited with status ${status} (cmd: ${script})","messagePattern":"shared-volume init for (.+?) exited with status (.+?) \\(cmd: (.+?)\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java","lineNumber":327,"sourceCode":"        String image = (initImage != null && !initImage.isBlank()) ? initImage : \"busybox:stable\";\n        imageCacheService.ensureImageExists(image);\n\n        HostConfig hostConfig = HostConfig.newHostConfig().withMounts(List.of(\n                new Mount().withType(MountType.VOLUME).withSource(volumeName).withTarget(mount)));\n        CreateContainerResponse created = dockerClient.createContainerCmd(image)\n                .withHostConfig(hostConfig)\n                .withCmd(\"sh\", \"-c\", script.toString())\n                .exec();\n        String helperId = created.getId();\n        try {\n            dockerClient.startContainerCmd(helperId).exec();\n            Integer status = dockerClient.waitContainerCmd(helperId)\n                    .exec(new WaitContainerResultCallback())\n                    .awaitStatusCode(60, TimeUnit.SECONDS);\n            if (status == null || status != 0) {\n                // Throw so the caller leaves the volume unmemoised and retries on the next launch,\n                // rather than leaving it root:root 0755 with no further attempt.\n                throw new IllegalStateException(\"shared-volume init for \" + volumeName\n                        + \" exited with status \" + status + \" (cmd: \" + script + \")\");\n            }\n            LOG.infov(\"Initialised shared volume {0} root (cmd: {1})\", volumeName, script);\n        } finally {\n            try {\n                dockerClient.removeContainerCmd(helperId).withForce(true).exec();\n            } catch (Exception ignore) {\n                // best-effort cleanup of the one-off helper\n            }\n        }\n    }\n\n    /**\n     * Removes a named Docker volume, ignoring errors if it does not exist or is still in use.\n     * Returns whether the volume is confirmed gone: true if it was removed or was already absent,\n     * false if Docker refused (e.g. still in use by a container) or the attempt failed for some\n     * other reason (e.g. a transient daemon error). Callers that need to retry a removal should\n     * treat false as \"unconfirmed, try again later\" rather than \"definitely still there\" - a single","sourceCodeStart":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/floci-io/floci/blob/62ff490619e7bd3554597c28c704081b4c15add5/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java#L309-L345","documentation":"Thrown by ContainerLifecycleManager.initSharedVolumeRoot when the one-off helper container that chowns/chmods the shared volume root exits with a non-zero status (or the 60-second wait times out and status is null). The message includes the volume name, exit status, and the exact sh -c script. Throwing leaves the volume unmemoised so the next launch retries rather than permanently shipping a root:root 0755 root.","triggerScenarios":"The helper container's script fails: busybox chown on an unknown uid without a gid, the init image lacking /bin/sh, Docker daemon problems, or the wait exceeding 60 seconds. The command shown in the message identifies which step failed.","commonSituations":"Custom init image that is distroless or scratch (no sh); Docker socket permission issues; volume driver (EFS) mount problems on the host; extremely slow chown on a huge existing volume exceeding the 60s wait.","solutions":["Run the reported cmd script manually in a container to see the real error: docker run --rm -v <vol>:/data <init-image> sh -c '<cmd from message>'","If using a custom init image, ensure it provides a POSIX sh and chown/chmod (busybox-based images work)","Fix the ownership config (uid/gid must exist or be numeric) so chown succeeds","If the volume is large and chown is slow, pre-initialize the volume manually or increase capacity/patience and retry the launch"],"exampleFix":"# before: distroless init image, no shell\nfloci.storage.efs.init-image: my/distroless:latest\n\n# after:\nfloci.storage.efs.init-image: busybox:1.36","handlingStrategy":"retry","validationCode":"boolean imageHasShell(String image) throws Exception {\n    // smoke-test the init image before first use\n    Process p = new ProcessBuilder(\"docker\", \"run\", \"--rm\", image, \"sh\", \"-c\", \"command -v chown\").start();\n    return p.waitFor(30, TimeUnit.SECONDS) && p.exitValue() == 0;\n}","typeGuard":null,"tryCatchPattern":"try {\n    launcher.launch();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"shared-volume init\")) { runReportedCmdManually(); fixRootCause(); retryLaunch(); }\n}","preventionTips":["Use a busybox-based init image that provides sh, chown, chmod","Verify the uid/gid you configure actually applies to the volume's filesystem","Pre-initialize large volumes manually so the 60s helper window is not exceeded","Keep the error's cmd string in logs — it reproduces the failure directly"],"tags":["docker","efs","shared-volume","init-failure","container"],"backgroundTag":null,"analyzedSha":"62ff490619e7bd3554597c28c704081b4c15add5","analyzedAt":"2026-08-14T14:25:23.764Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}