apache/maven · error · IllegalStateException

Error reading config file: ${atFile}

Error message

Error reading config file: ${atFile}

What it means

While reading the `@argfile` given on the mvn command line, Files.lines threw an IOException, rethrown as IllegalStateException 'Error reading config file' with the path. The file could not be opened or read as UTF-8: it is missing, a directory, permission-denied, a dangling symlink, or hit an I/O error mid-read. Parsing never started - this is a filesystem-level failure.

Source

Thrown at impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenParser.java:75

    protected MavenOptions parseMavenCliOptions(List<String> args) {
        try {
            return parseArgs(Options.SOURCE_CLI, args);
        } catch (ParseException e) {
            throw new IllegalArgumentException("Failed to parse CLI arguments: " + e.getMessage(), e.getCause());
        }
    }

    protected MavenOptions parseMavenAtFileOptions(Path atFile) {
        try (Stream<String> lines = Files.lines(atFile, StandardCharsets.UTF_8)) {
            List<String> args =
                    lines.filter(arg -> !arg.isEmpty() && !arg.startsWith("#")).toList();
            return parseArgs("atFile", args);
        } catch (ParseException e) {
            throw new IllegalArgumentException(
                    "Failed to parse arguments from file (" + atFile + "): " + e.getMessage(), e.getCause());
        } catch (IOException e) {
            throw new IllegalStateException("Error reading config file: " + atFile, e);
        }
    }

    protected MavenOptions parseMavenConfigOptions(Path configFile) {
        try (Stream<String> lines = Files.lines(configFile, StandardCharsets.UTF_8)) {
            List<String> args =
                    lines.filter(arg -> !arg.isEmpty() && !arg.startsWith("#")).toList();
            MavenOptions options = parseArgs("maven.config", args);
            if (options.goals().isPresent()) {
                // This file can only contain options, not args (goals or phases)
                throw new IllegalArgumentException("Unrecognized entries in maven.config (" + configFile + ") file: "
                        + options.goals().get());
            }
            return options;
        } catch (ParseException e) {
            throw new IllegalArgumentException(
                    "Failed to parse arguments from maven.config file (" + configFile + "): " + e.getMessage(),
                    e.getCause());

View on GitHub (pinned to e4093d4e12)

Solutions

1. Verify the path printed in the message: `ls -l <atFile>`.
2. Use an absolute path, or resolve the relative path against the directory mvn runs from.
3. Fix permissions (`chmod a+r`) or ownership so the build user can read the file.
4. Make sure the path is a regular file, not a directory or broken symlink.

Example fix

# before: run from a directory other than the project root
mvn @build.args   # build.args lives in the project root

# after: absolute path
mvn @/checkout/myproject/build.args

if (!Files.isReadable(atFile) || !Files.isRegularFile(atFile)) {
    throw new IllegalArgumentException("@argfile missing or unreadable: " + atFile);
}

When it happens

Trigger: `mvn @/path/that/does/not/exist`, an @file with mode bits that deny read to the build user, the path resolving to a directory, or the file being replaced/deleted while Maven reads it.

Common situations: Relative @file paths resolved from a different CI working directory; files created by root with a restrictive umask inside containers; symlinks whose targets are not checked out.

Related errors

• Failed to parse arguments from file (${atFile}): ${message}
• Error reading config file: ${configFile}
• Unbounded range: {}
• Ranges overlap: {}
• Range defies version ordering: {}

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/466c43f1d84bb40b. Report an issue: GitHub.