floci-io/floci · critical · IllegalArgumentException

floci.storage.efs root-permissions must be 3-4 octal digits

Error message

floci.storage.efs root-permissions must be 3-4 octal digits (e.g. "0777", or "2775" for setgid): ${permissions}

What it means

Thrown by ContainerLifecycleManager.ensureSharedVolume when the configured root-permissions string for an EFS shared volume does not match ^[0-7]{3,4}$ (3-4 octal digits). Validation happens before the value is spliced into the init helper's 'sh -c' script, mirroring EFS CreationInfo.Permissions, so a typo cannot produce a mangled script that soft-fails.

Source

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

     */
    public void ensureSharedVolume(String volumeName, OptionalInt ownerUid, OptionalInt ownerGid,
                                   Optional<String> rootPermissions, String initImage) {
        ensureVolume(volumeName);
        if (rootPermissions.isEmpty() && ownerUid.isEmpty() && ownerGid.isEmpty()) {
            return;
        }
        // An EFS access point's CreationInfo requires OwnerUid and OwnerGid together; reject a
        // partial ownership config rather than emitting a malformed `chown uid:` (whose trailing
        // colon makes chown resolve the login group and fail in busybox for an unknown uid).
        if (ownerUid.isPresent() != ownerGid.isPresent()) {
            throw new IllegalArgumentException(
                    "floci.storage.efs owner-uid and owner-gid must be set together");
        }
        // Validate before splicing into the helper's `sh -c`, matching CreationInfo.Permissions
        // (^[0-7]{3,4}$), so a typo can't produce a mangled script that soft-fails.
        rootPermissions.ifPresent(p -> {
            if (!p.matches("^[0-7]{3,4}$")) {
                throw new IllegalArgumentException(
                        "floci.storage.efs root-permissions must be 3-4 octal digits (e.g. \"0777\","
                                + " or \"2775\" for setgid): " + p);
            }
        });
        // computeIfAbsent runs the one-off init under a per-volume lock, so a concurrent launch for
        // the same volume waits for it to finish rather than mounting a still root:root 0755 root.
        // Returning null on failure leaves the volume unmemoised, so the next launch retries.
        initializedSharedVolumes.computeIfAbsent(volumeName, k -> {
            try {
                initSharedVolumeRoot(volumeName, ownerUid, ownerGid, rootPermissions, initImage);
                return Boolean.TRUE;
            } catch (RuntimeException e) {
                LOG.warnv("Failed to initialise shared volume {0} ownership: {1}", volumeName, e.getMessage());
                return null;
            }
        });
    }

View on GitHub (pinned to 62ff490619)

Solutions

Use a 3- or 4-digit octal string such as "0777" or "2775" (4th digit = setgid/setuid/sticky)
Quote the value in YAML to avoid it being interpreted as another type
Restart floci after correcting the config

Example fix

# before
floci.storage.efs.root-permissions: rwxrwxrwx

# after
floci.storage.efs.root-permissions: "0777"

Defensive patterns

Strategy: validation

Validate before calling

boolean validPermissions(String p) {
    return p != null && p.matches("^[0-7]{3,4}$");
}

Try / catch

try {
    manager.ensureSharedVolume(vol, ownerUid, ownerGid, perms, initImage);
} catch (IllegalArgumentException e) {
    // fix root-permissions to 3-4 octal digits, then retry
}

Prevention

Always use octal mode strings in config, never symbolic notation
Quote mode strings in YAML
Copy the example values ("0777", "2775") from the docs

When it happens

Trigger: Setting floci.storage.efs.root-permissions (or FLOCI_STORAGE_EFS_ROOT_PERMISSIONS) to values like "7775x", "rwxr-xr-x", "77", or "07777" — anything outside 3-4 octal characters.

Common situations: Using symbolic permission notation instead of octal; copy-paste typos; adding a 5-digit mode or trailing whitespace; assuming a leading quote character is stripped by YAML when it is not.

Related errors

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