apereo/cas · critical · IllegalArgumentException

Metadata directory location cannot be located/created

Error message

Metadata directory location  cannot be located/created

What it means

FileSystemSamlIdPMetadataLocator.initializeMetadataDirectory() ensures the configured on-disk metadata directory exists. If the directory does not exist and File.mkdir() fails (e.g. parent missing, permissions), it throws IllegalArgumentException stating the location cannot be located or created. Called from initialize() and getMetadataArtifact().

Solutions

1. Pre-create the directory including parents: mkdir -p /path/to/metadata, and ensure the CAS process user owns/can write it.
2. Set the location to an existing, writable directory in cas.authn.samlIdp.metadata.file-system.location.
3. If running in a container, verify the volume mount exists and its permissions allow the CAS user to write.
4. Check the path isn't an existing regular file; remove/rename it so the directory can be created.

Example fix

// before
cas.authn.samlIdp.metadata.file-system.location=/etc/cas/saml/metadata/idp   // parents missing, no perms

// after
sudo mkdir -p /etc/cas/saml/metadata/idp && sudo chown cas:cas /etc/cas/saml/metadata/idp
cas.authn.samlIdp.metadata.file-system.location=/etc/cas/saml/metadata/idp

// before starting CAS / configuring the locator
Path loc = Path.of(location);
if (!Files.isDirectory(loc)) {
    Files.createDirectories(loc); // creates parents, fails loudly on permission issues
}
if (!Files.isWritable(loc)) throw new IllegalStateException("Metadata dir not writable: " + loc);

try {
    locator.initialize();
} catch (IllegalArgumentException e) {
    logger.error("Fix metadata dir at {}: {}", configuredLocation, e.getMessage());
}

When it happens

Trigger: metadataLocation (cas.authn.samlIdp.metadata.file-system.location) does not exist and mkdir() returns false — parent directory absent (mkdir is not mkdirs), insufficient write permission, or path is a file.

Common situations: Configured location points several levels deep where no parent exists; running CAS as a non-root user without write access to the path; container volume not mounted; path accidentally set to a file.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Metadata directory location cannot be located/created
• Metadata artifact at
• No assertion consumer service could be found for entity
• Endpoint for is not available or does not define a binding…
• Endpoint for does not define a binding or location for…

AI-assisted analysis of apereo/cas@e7288fc434 (2026-09-08). Data as JSON: /api/errors/3c9dddb1069b11da. Report an issue: GitHub.

Appendix: source

Thrown at support/cas-server-support-saml-idp-core/src/main/java/org/apereo/cas/support/saml/idp/metadata/locator/FileSystemSamlIdPMetadataLocator.java:139

        }
        initializeMetadataDirectory();
        val resource = ResourceUtils.toFileSystemResource(new File(this.metadataLocation, artifactName));
        if (resource.exists() && resource.isReadable()) {
            val content = FileUtils.readFileToString(resource.getFile(), StandardCharsets.UTF_8);
            if (StringUtils.isNotBlank(content)) {
                return resolveContentToResource(content);
            }
            LOGGER.warn("Metadata artifact at [{}] is empty and invalid and will be deleted", resource);
            FileUtils.deleteQuietly(resource.getFile());
        }
        return ResourceUtils.toFileSystemResource(resource.getFile());
    }

    protected void initializeMetadataDirectory() {
        if (!this.metadataLocation.exists()) {
            LOGGER.debug("Metadata directory [{}] does not exist. Creating...", this.metadataLocation);
            if (!this.metadataLocation.mkdir()) {
                throw new IllegalArgumentException("Metadata directory location " + this.metadataLocation + " cannot be located/created");
            }
        }
    }
}

View on GitHub (pinned to e7288fc434)