quarkusio/quarkus · error · IllegalArgumentException

Path not specified

Error message

Path not specified

What it means

PathMatcher.addPrefixPath throws this IllegalArgumentException when an empty string is passed as the path for a prefix route registration. The library requires a non-empty path; the root path must be expressed as "/" (which sets the defaultHandler), not "".

Source

Thrown at independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/mapping/PathMatcher.java:87

        private T defaultHandler;
        private final SubstringMap.Builder<T> pathsBuilder = new SubstringMap.Builder<>();

        /**
         * Adds a path prefix and a handler for that path. If the path does not start
         * with a / then one will be prepended.
         * <p>
         * The match is done on a prefix bases, so registering /foo will also match /bar. Exact
         * path matches are taken into account first.
         * <p>
         * If / is specified as the path then it will replace the default handler.
         *
         * @param path The path
         * @param handler The handler
         */
        void addPrefixPath(final String path, final T handler) {
            if (path.isEmpty()) {
                throw new IllegalArgumentException("Path not specified");
            }

            if (STRING_PATH_SEPARATOR.equals(path)) {
                this.defaultHandler = handler;
                return;
            } else if (path.endsWith(STRING_PATH_SEPARATOR)) {
                throw new RuntimeException("Prefix path cannot end with /");
            }

            pathsBuilder.put(path, handler);
        }

        private int[] buildLengths(SubstringMap<T> paths) {
            final Set<Integer> lengths = new TreeSet<>(new Comparator<>() {
                @Override
                public int compare(Integer o1, Integer o2) {
                    return -o1.compareTo(o2);
                }

View on GitHub (pinned to e1c734241f)

Solutions

1. Use "/" instead of "" when registering the root prefix path
2. Normalize the path before calling addPrefixPath (e.g. path.isEmpty() ? "/" : path)
3. Check the @Path annotation value that produced the empty path and fix it to "/" or a valid sub-path

Example fix

// before
matcher.addPrefixPath(path, handler); // path == ""

// after
String normalized = path == null || path.isEmpty() ? "/" : path;
matcher.addPrefixPath(normalized, handler);

if (path == null || path.isEmpty()) {
    throw new IllegalArgumentException("Prefix path must be non-empty; use \"/\" for the root");
}

try {
    matcher.addPrefixPath(path, handler);
} catch (IllegalArgumentException e) {
    if ("Path not specified".equals(e.getMessage())) {
        matcher.addPrefixPath("/", handler); // fall back to root
    } else throw e;
}

When it happens

Trigger: Calling PathMatcher.addPrefixPath("", handler) — e.g. programmatically registering a route or misconfigured @Path("") mapping that resolves to an empty prefix during route building.

Common situations: Custom route registration code passing a blank path variable; annotation processing where @Path value is empty and not normalized to "/"; framework integrations that strip slashes incorrectly before registering prefixes.

Related errors

• Prefix path cannot end with /
• Invalid template ${template}
• Invalid template ${template} Unmatched { braces
• Name cannot start with '/':${name}
• Predicate already set

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