{"record":{"id":"1f9a4dd367372121","repo":"floci-io/floci","slug":"floci-storage-efs-root-permissions-must-be-3-4-oct","errorCode":null,"errorMessage":"floci.storage.efs root-permissions must be 3-4 octal digits (e.g. \"0777\", or \"2775\" for setgid): ${permissions}","messagePattern":"floci\\.storage\\.efs root-permissions must be 3-4 octal digits \\(e\\.g\\. \"0777\", or \"2775\" for setgid\\): (.+?)","errorType":"console","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java","lineNumber":276,"sourceCode":"     */\n    public void ensureSharedVolume(String volumeName, OptionalInt ownerUid, OptionalInt ownerGid,\n                                   Optional<String> rootPermissions, String initImage) {\n        ensureVolume(volumeName);\n        if (rootPermissions.isEmpty() && ownerUid.isEmpty() && ownerGid.isEmpty()) {\n            return;\n        }\n        // An EFS access point's CreationInfo requires OwnerUid and OwnerGid together; reject a\n        // partial ownership config rather than emitting a malformed `chown uid:` (whose trailing\n        // colon makes chown resolve the login group and fail in busybox for an unknown uid).\n        if (ownerUid.isPresent() != ownerGid.isPresent()) {\n            throw new IllegalArgumentException(\n                    \"floci.storage.efs owner-uid and owner-gid must be set together\");\n        }\n        // Validate before splicing into the helper's `sh -c`, matching CreationInfo.Permissions\n        // (^[0-7]{3,4}$), so a typo can't produce a mangled script that soft-fails.\n        rootPermissions.ifPresent(p -> {\n            if (!p.matches(\"^[0-7]{3,4}$\")) {\n                throw new IllegalArgumentException(\n                        \"floci.storage.efs root-permissions must be 3-4 octal digits (e.g. \\\"0777\\\",\"\n                                + \" or \\\"2775\\\" for setgid): \" + p);\n            }\n        });\n        // computeIfAbsent runs the one-off init under a per-volume lock, so a concurrent launch for\n        // the same volume waits for it to finish rather than mounting a still root:root 0755 root.\n        // Returning null on failure leaves the volume unmemoised, so the next launch retries.\n        initializedSharedVolumes.computeIfAbsent(volumeName, k -> {\n            try {\n                initSharedVolumeRoot(volumeName, ownerUid, ownerGid, rootPermissions, initImage);\n                return Boolean.TRUE;\n            } catch (RuntimeException e) {\n                LOG.warnv(\"Failed to initialise shared volume {0} ownership: {1}\", volumeName, e.getMessage());\n                return null;\n            }\n        });\n    }\n","sourceCodeStart":258,"sourceCodeEnd":294,"githubUrl":"https://github.com/floci-io/floci/blob/62ff490619e7bd3554597c28c704081b4c15add5/src/main/java/io/github/hectorvent/floci/core/common/docker/ContainerLifecycleManager.java#L258-L294","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nfloci.storage.efs.root-permissions: rwxrwxrwx\n\n# after\nfloci.storage.efs.root-permissions: \"0777\"","handlingStrategy":"validation","validationCode":"boolean validPermissions(String p) {\n    return p != null && p.matches(\"^[0-7]{3,4}$\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    manager.ensureSharedVolume(vol, ownerUid, ownerGid, perms, initImage);\n} catch (IllegalArgumentException e) {\n    // fix root-permissions to 3-4 octal digits, then retry\n}","preventionTips":["Always use octal mode strings in config, never symbolic notation","Quote mode strings in YAML","Copy the example values (\"0777\", \"2775\") from the docs"],"tags":["docker","efs","config","permissions","validation"],"backgroundTag":null,"analyzedSha":"62ff490619e7bd3554597c28c704081b4c15add5","analyzedAt":"2026-08-14T14:25:23.764Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}