{"record":{"id":"18fe21c9bf78fdc8","repo":"apereo/cas","slug":"cannot-read-load-from-subordinate-directory","errorCode":null,"errorMessage":"Cannot read/load from subordinate directory","messagePattern":"Cannot read/load from subordinate directory","errorType":"console","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"support/cas-server-support-oidc-federation/src/main/java/org/apereo/cas/oidc/federation/subordinate/OidcFederationSubordinateRepository.java","lineNumber":55,"sourceCode":"    protected void loadSubordinates(final String subordinateDirectory) {\n        if (StringUtils.isNotBlank(subordinateDirectory)) {\n            LOGGER.debug(\"Loading subordinates...\");\n            val dir = Paths.get(subordinateDirectory);\n            if (!Files.exists(dir)) {\n                throw new IllegalArgumentException(\"subordinate directory [%s] does not exist\".formatted(subordinateDirectory));\n            }\n            if (!Files.isDirectory(dir)) {\n                throw new IllegalArgumentException(\"subordinate directory [%s] is not a directory\".formatted(subordinateDirectory));\n            }\n            try (val stream = Files.walk(dir).filter(Files::isRegularFile).filter(Files::isReadable)) {\n                stream.forEach(path -> FunctionUtils.doUnchecked(_ -> {\n                    val file = path.toFile();\n                    LOGGER.debug(\"Parsing [{}]...\", file);\n                    val subordinate = MAPPER.readValue(file, OidcFederationSubordinate.class);\n                    subordinates.put(subordinate.getEntityId(), subordinate);\n                }));\n            } catch (final IOException e) {\n                throw new IllegalArgumentException(\"Cannot read/load from subordinate directory\", e);\n            }\n            LOGGER.info(\"Loaded [{}] subordinates\", subordinates.size());\n        }\n    }\n}\n","sourceCodeStart":37,"sourceCodeEnd":61,"githubUrl":"https://github.com/apereo/cas/blob/e7288fc434b4f4505b8452e1a57e8fb3111bb863/support/cas-server-support-oidc-federation/src/main/java/org/apereo/cas/oidc/federation/subordinate/OidcFederationSubordinateRepository.java#L37-L61","documentation":"After validating the directory, loadSubordinates() walks it and parses each file with Jackson into OidcFederationSubordinate; any IOException while reading or walking (unreadable file, I/O error mid-walk) is rethrown as IllegalArgumentException with this message and the original cause attached.","triggerScenarios":"A regular file inside the directory cannot be read or a Files.walk()/readValue() I/O error occurs during repository construction at CAS startup.","commonSituations":"Files owned by another user with no read permission for the CAS process; broken symlink or special file inside the directory; NFS mount dropped mid-startup; truncated/locked file.","solutions":["Inspect the wrapped cause (getCause()) to identify the failing file, then fix its permissions: chmod/chown so the CAS user can read it","Remove non-JSON junk (broken symlinks, sockets) from the directory","Verify the filesystem is accessible from the CAS process (mount health, container volume)","Note: individual JSON parse failures surface differently (UncheckedIOException via doUnchecked); this message is I/O-level"],"exampleFix":"// before\nls -l /etc/cas/oidc/subordinates\n-rw------- root root acme.json   # CAS user cannot read\n// after\nchown cas:cas /etc/cas/oidc/subordinates/acme.json\nchmod 640 /etc/cas/oidc/subordinates/acme.json","handlingStrategy":"try-catch","validationCode":"try (var s = Files.walk(Paths.get(subordinateDirectory))) {\n    s.filter(Files::isRegularFile).forEach(p -> {\n        if (!Files.isReadable(p)) throw new IllegalStateException(\"Unreadable: \" + p);\n    });\n} catch (IOException e) { /* provision error */ }","typeGuard":null,"tryCatchPattern":"try {\n    repository = new OidcFederationSubordinateRepository(...);\n} catch (IllegalArgumentException e) {\n    LOGGER.error(\"Subordinate load I/O failed\", e.getCause());\n}","preventionTips":["Run CAS under a user with read access to all subordinate files","Keep only regular JSON files in the directory","Monitor filesystem/NFS health in deployment"],"tags":["filesystem","io","startup"],"backgroundTag":"file-read-failed","analyzedSha":"e7288fc434b4f4505b8452e1a57e8fb3111bb863","analyzedAt":"2026-09-08T15:39:16.015Z","contentChangedAt":"2026-09-08T15:39:16.015Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}