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

PathCollection.getSinglePath() is a convenience for collections known to hold exactly one path. It throws IllegalStateException when the collection has any size other than 1. The message reports the actual size, e.g. '...but contains 3'.

Source

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

package io.quarkus.paths;

import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Stream;

public interface PathCollection extends Iterable<Path> {

    boolean isEmpty();

    int size();

    boolean isSinglePath();

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

    boolean contains(Path path);

    PathCollection add(Path... paths);

    PathCollection addFirst(Path... paths);

    PathCollection addAllFirst(Iterable<Path> i);

    Path resolveExistingOrNull(String path);

    default Stream<Path> stream() {
        final List<Path> list = new ArrayList<>(size());
        for (Path p : this) {
            list.add(p);

View on GitHub (pinned to e1c734241f)

Solutions

1. Check isSinglePath() before calling getSinglePath().
2. Handle the multi-path case by iterating the collection instead of taking one element.
3. If you expected exactly one path, fix the environment (remove duplicate classpath entries / restore the missing dependency).
4. Catch IllegalStateException and fall back to iteration if multiple paths are acceptable.

Example fix

// before
Path single = pathCollection.getSinglePath(); // IllegalStateException when size != 1
// after
Path single = pathCollection.isSinglePath()
        ? pathCollection.getSinglePath()
        : pathCollection.iterator().next();

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

static boolean hasSinglePath(PathCollection c) {
    return c != null && c.isSinglePath();
}

try {
    Path single = pathCollection.getSinglePath();
} catch (IllegalStateException e) {
    Path first = pathCollection.iterator().hasNext() ? pathCollection.iterator().next() : null;
    // fall back to first element or handle empty
}

When it happens

Trigger: Calling getSinglePath() on a PathCollection whose size() != 1 — e.g. a multi-release or classpath element that resolved to 0 paths (missing artifact) or multiple paths (several classpath entries / duplicate locations).

Common situations: Calling it on getClassPaths()/application roots during Quarkus dev mode where multiple class directories exist; calling it on an empty collection after a dependency was excluded; assuming a single-location deployment when running in dev or test mode.

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/ddf624cb185a0f9d. Report an issue: GitHub.