apache/maven · error · IllegalStateException

Error reading config file: ${configFile}

Error message

Error reading config file: ${configFile}

What it means

Maven could not read .mvn/maven.config: Files.lines threw IOException, rethrown as IllegalStateException 'Error reading config file' with the path. The file was confirmed to exist before parsing, so this is an open/read failure: permission denied to the build user, a symlink with a missing target, or an I/O error during the read.

Source

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

    }

    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());
        } catch (IOException e) {
            throw new IllegalStateException("Error reading config file: " + configFile, e);
        }
    }

    protected MavenOptions parseArgs(String source, List<String> args) throws ParseException {
        return CommonsCliMavenOptions.parse(source, args.toArray(new String[0]));
    }
}

View on GitHub (pinned to e4093d4e12)

Solutions

1. `ls -l .mvn/maven.config` - confirm owner and mode allow the build user to read it.
2. `chmod a+r .mvn/maven.config` or chown it to the build user.
3. If it is a symlink, make its target exist and be readable.
4. Commit a static file instead of regenerating it per build; avoid editing it while builds start.

Example fix

# before: root-owned file, CI user cannot read it
$ ls -l .mvn/maven.config
-rw------- 1 root root 48 maven.config

# after
$ chmod a+r .mvn/maven.config
$ mvn -v

if (Files.exists(configFile) && !Files.isReadable(configFile)) {
    throw new IllegalStateException("maven.config not readable by build user: " + configFile);
}

When it happens

Trigger: maven.config owned by another user with no read permission (containers running as non-root), a symlink whose target was not checked out, or the file being atomically replaced by an editor exactly while a build starts reading it.

Common situations: Docker builds mounting root-owned project directories; CI caches that restore a broken symlink; tooling that rewrites maven.config on every build racing concurrent invocations.

Related errors

• Error reading config file: ${atFile}
• Error while deploying metadata: {}
• Unrecognized maven.config file entries: {}
• Unrecognized entries in maven.config (${configFile}) file: $
• Failed to parse arguments from maven.config file (${configFi

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