quarkusio/quarkus · error · java.lang.IllegalStateException

Paths collection expected to contain a single path but conta

Error message

Paths collection expected to contain a single path but contains 

What it means

PathList.getSinglePath() returns the only element of the list and throws IllegalStateException if the list contains anything other than exactly one path. It mirrors PathCollection.getSinglePath() for the List-backed implementation; the message includes the actual size.

Source

Thrown at independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathList.java:81

    private PathList(List<Path> paths) {
        this.paths = Collections.unmodifiableList(paths);
    }

    public boolean isEmpty() {
        return paths.isEmpty();
    }

    public int size() {
        return paths.size();
    }

    public boolean isSinglePath() {
        return paths.size() == 1;
    }

    public Path getSinglePath() {
        if (paths.size() != 1) {
            throw new IllegalStateException("Paths collection expected to contain a single path but contains " + paths.size());
        }
        return paths.get(0);
    }

    @Override
    public Iterator<Path> iterator() {
        return paths.iterator();
    }

    public boolean contains(Path path) {
        return paths.contains(path);
    }

    public PathList add(Path... paths) {
        final List<Path> list = new ArrayList<>(this.paths.size() + paths.length);
        list.addAll(this.paths);
        Collections.addAll(list, paths);
        return new PathList(list);

View on GitHub (pinned to e1c734241f)

Solutions

1. Check isSinglePath() before calling getSinglePath().
2. Iterate the list when multiple entries are legitimate.
3. Fix the environment when one path was expected but several were resolved (deduplicate classpath).
4. Catch IllegalStateException and choose a deterministic entry (e.g. first) if that is acceptable.

Example fix

// before
Path only = pathList.getSinglePath(); // throws unless size == 1
// after
if (!pathList.isSinglePath()) {
    throw new IllegalStateException("Expected one path, got " + pathList.size());
}
Path only = pathList.getSinglePath();

if (pathList == null || pathList.size() != 1) {
    throw new IllegalStateException("Expected exactly one path, got " + (pathList == null ? "null" : pathList.size()));
}

static boolean hasSinglePath(PathList list) {
    return list != null && list.isSinglePath();
}

try {
    Path only = pathList.getSinglePath();
} catch (IllegalStateException e) {
    log.warnf("PathList had %d entries, using first", pathList.size());
    Path only = pathList.isEmpty() ? null : pathList.get(0);
}

When it happens

Trigger: Calling getSinglePath() on a PathList with 0 elements (no resolved paths) or with 2+ elements (multiple classpath/directory entries).

Common situations: Assuming the app has a single classpath root in dev mode (where target/classes plus test classes may both be present); calling after a dependency resolution that produced an empty list; duplicate entries from Gradle/Maven classpath aggregation.

Related errors

• Paths collection expected to contain a single path but conta
• Please add an extension that provides a CSRF prevention feat
• rootPath is null for
• Expected : after attribute
• Failed to load CodeGenProvider class from deployment classlo

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/03e54ec86336e99d. Report an issue: GitHub.