{"record":{"id":"03e54ec86336e99d","repo":"quarkusio/quarkus","slug":"paths-collection-expected-to-contain-a-single-path-03e54e","errorCode":null,"errorMessage":"Paths collection expected to contain a single path but contains ","messagePattern":"Paths collection expected to contain a single path but contains ","errorType":"exception","errorClass":"java.lang.IllegalStateException","httpStatus":null,"severity":"error","filePath":"independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathList.java","lineNumber":81,"sourceCode":"    private PathList(List<Path> paths) {\n        this.paths = Collections.unmodifiableList(paths);\n    }\n\n    public boolean isEmpty() {\n        return paths.isEmpty();\n    }\n\n    public int size() {\n        return paths.size();\n    }\n\n    public boolean isSinglePath() {\n        return paths.size() == 1;\n    }\n\n    public Path getSinglePath() {\n        if (paths.size() != 1) {\n            throw new IllegalStateException(\"Paths collection expected to contain a single path but contains \" + paths.size());\n        }\n        return paths.get(0);\n    }\n\n    @Override\n    public Iterator<Path> iterator() {\n        return paths.iterator();\n    }\n\n    public boolean contains(Path path) {\n        return paths.contains(path);\n    }\n\n    public PathList add(Path... paths) {\n        final List<Path> list = new ArrayList<>(this.paths.size() + paths.length);\n        list.addAll(this.paths);\n        Collections.addAll(list, paths);\n        return new PathList(list);","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathList.java#L63-L99","documentation":"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.","triggerScenarios":"Calling getSinglePath() on a PathList with 0 elements (no resolved paths) or with 2+ elements (multiple classpath/directory entries).","commonSituations":"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.","solutions":["Check isSinglePath() before calling getSinglePath().","Iterate the list when multiple entries are legitimate.","Fix the environment when one path was expected but several were resolved (deduplicate classpath).","Catch IllegalStateException and choose a deterministic entry (e.g. first) if that is acceptable."],"exampleFix":"// before\nPath only = pathList.getSinglePath(); // throws unless size == 1\n// after\nif (!pathList.isSinglePath()) {\n    throw new IllegalStateException(\"Expected one path, got \" + pathList.size());\n}\nPath only = pathList.getSinglePath();","handlingStrategy":"type-guard","validationCode":"if (pathList == null || pathList.size() != 1) {\n    throw new IllegalStateException(\"Expected exactly one path, got \" + (pathList == null ? \"null\" : pathList.size()));\n}","typeGuard":"static boolean hasSinglePath(PathList list) {\n    return list != null && list.isSinglePath();\n}","tryCatchPattern":"try {\n    Path only = pathList.getSinglePath();\n} catch (IllegalStateException e) {\n    log.warnf(\"PathList had %d entries, using first\", pathList.size());\n    Path only = pathList.isEmpty() ? null : pathList.get(0);\n}","preventionTips":["Gate calls behind isSinglePath().","Deduplicate classpath entries before building PathList if a single entry is required.","Treat empty lists as a distinct failure case from multi-entry lists.","Prefer iterating over getSinglePath() unless singleness is guaranteed by design."],"tags":["illegal-state","collections","quarkus-paths","classpath"],"backgroundTag":"unexpected-collection-size","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}