floci-io/floci · critical · IllegalStateException

shared-volume init for ${volumeName} exited with status ${st

Error message

shared-volume init for ${volumeName} exited with status ${status} (cmd: ${script})

What it means

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.

Source

Thrown at src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java:327

        String image = (initImage != null && !initImage.isBlank()) ? initImage : "busybox:stable";
        imageCacheService.ensureImageExists(image);

        HostConfig hostConfig = HostConfig.newHostConfig().withMounts(List.of(
                new Mount().withType(MountType.VOLUME).withSource(volumeName).withTarget(mount)));
        CreateContainerResponse created = dockerClient.createContainerCmd(image)
                .withHostConfig(hostConfig)
                .withCmd("sh", "-c", script.toString())
                .exec();
        String helperId = created.getId();
        try {
            dockerClient.startContainerCmd(helperId).exec();
            Integer status = dockerClient.waitContainerCmd(helperId)
                    .exec(new WaitContainerResultCallback())
                    .awaitStatusCode(60, TimeUnit.SECONDS);
            if (status == null || status != 0) {
                // Throw so the caller leaves the volume unmemoised and retries on the next launch,
                // rather than leaving it root:root 0755 with no further attempt.
                throw new IllegalStateException("shared-volume init for " + volumeName
                        + " exited with status " + status + " (cmd: " + script + ")");
            }
            LOG.infov("Initialised shared volume {0} root (cmd: {1})", volumeName, script);
        } finally {
            try {
                dockerClient.removeContainerCmd(helperId).withForce(true).exec();
            } catch (Exception ignore) {
                // best-effort cleanup of the one-off helper
            }
        }
    }

    /**
     * Removes a named Docker volume, ignoring errors if it does not exist or is still in use.
     * Returns whether the volume is confirmed gone: true if it was removed or was already absent,
     * false if Docker refused (e.g. still in use by a container) or the attempt failed for some
     * other reason (e.g. a transient daemon error). Callers that need to retry a removal should
     * treat false as "unconfirmed, try again later" rather than "definitely still there" - a single

View on GitHub (pinned to 62ff490619)

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

Example fix

# before: distroless init image, no shell
floci.storage.efs.init-image: my/distroless:latest

# after:
floci.storage.efs.init-image: busybox:1.36

Defensive patterns

Strategy: retry

Validate before calling

boolean imageHasShell(String image) throws Exception {
    // smoke-test the init image before first use
    Process p = new ProcessBuilder("docker", "run", "--rm", image, "sh", "-c", "command -v chown").start();
    return p.waitFor(30, TimeUnit.SECONDS) && p.exitValue() == 0;
}

Try / catch

try {
    launcher.launch();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("shared-volume init")) { runReportedCmdManually(); fixRootCause(); retryLaunch(); }
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of floci-io/floci@62ff490619 (2026-08-14). Data as JSON: /api/errors/83a7409c34b6aac2. Report an issue: GitHub.