What causes "Unable to parse YAML file from ${composeFileAbsolutePath}" in testcontainers/testcontainers-java?

Inspect the cause exception's line/column to locate the YAML syntax error.

testcontainers/testcontainers-java · error · IllegalArgumentException

Unable to parse YAML file from

Error message

Unable to parse YAML file from ${composeFileAbsolutePath}

What it means

ParsedDockerComposeFile loads and parses a docker-compose YAML file using SnakeYAML. If the file cannot be read or the YAML is malformed, an IllegalArgumentException with the file's absolute path is thrown and the parse exception is set as the cause. This happens before any Testcontainers-specific validation.

Solutions

Inspect the cause exception's line/column to locate the YAML syntax error.
Validate the file with `docker-compose -f <file> config` or any YAML linter.
Ensure the File path points to an existing, readable compose file.
Replace tabs with spaces and fix indentation issues.

Example fix

// before
ParsedDockerComposeFile parsed = new ParsedDockerComposeFile(new File("dockr-compose.yml")); // typo: file missing/garbage
// after
File f = new File("docker-compose.yml");
if (!f.isFile() || !f.canRead()) throw new IllegalStateException("compose file missing: " + f);
ParsedDockerComposeFile parsed = new ParsedDockerComposeFile(f);

Defensive patterns

Strategy: validation

Validate before calling

File f = new File(path);
if (!f.isFile() || !f.canRead()) throw new IllegalStateException("compose file unreadable: " + f);
new org.yaml.snakeyaml.Yaml().load(java.nio.file.Files.readString(f.toPath())); // syntax pre-check

Try / catch

try { new ParsedDockerComposeFile(file); } catch (IllegalArgumentException e) { throw new ConfigurationException("Bad compose YAML: " + e.getCause().getMessage(), e); }

Prevention

Lint compose files in CI (yamllint / docker compose config).
Never hand-edit compose files with editors that insert tabs.
Keep test compose files in version control and validated.

When it happens

Trigger: Constructor `new ParsedDockerComposeFile(composeFile)` where yaml.load() throws: invalid YAML syntax (bad indentation, tabs, duplicate keys), unreadable file, or non-mapping root document.

Common situations: Hand-edited compose files with tab characters instead of spaces, truncated files from bad checkouts, wrong file path passed so an HTML error page or empty file is read, YAML anchors misused.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/8f3304957471909b. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/ParsedDockerComposeFile.java:63

        // The default is 50 and a big docker-compose.yml file can easily go above that number. 1,000 should give us some room
        LoaderOptions options = new LoaderOptions();
        options.setMaxAliasesForCollections(1_000);
        DumperOptions dumperOptions = new DumperOptions();

        SafeConstructor constructor = new SafeConstructor(options) {
            @Override
            protected Object constructObject(Node node) {
                if (node.getTag().equals(new Tag("!reset")) || node.getTag().equals(new Tag("!override"))) {
                    return null;
                }
                return super.constructObject(node);
            }
        };
        Yaml yaml = new Yaml(constructor, new Representer(dumperOptions), dumperOptions, options, new Resolver());
        try (FileInputStream fileInputStream = FileUtils.openInputStream(composeFile)) {
            composeFileContent = yaml.load(fileInputStream);
        } catch (Exception e) {
            throw new IllegalArgumentException("Unable to parse YAML file from " + composeFile.getAbsolutePath(), e);
        }
        this.composeFileName = composeFile.getAbsolutePath();
        this.composeFile = composeFile;
        parseAndValidate();
    }

    @VisibleForTesting
    ParsedDockerComposeFile(Map<String, Object> testContent) {
        this.composeFileContent = testContent;
        this.composeFileName = "";
        this.composeFile = new File(".");

        parseAndValidate();
    }

    private void parseAndValidate() {
        final Map<String, ?> servicesMap;
        if (composeFileContent.containsKey("version") && "2.0".equals(composeFileContent.get("version"))) {

View on GitHub (pinned to 8e549514e3)