quarkusio/quarkus · error · IOException

Failed to locate the origin of ${name}

Error message

Failed to locate the origin of ${name}

What it means

getResourceOrigin(ClassLoader, name) locates a resource (e.g. a class file of BootstrapMavenOptions) via cl.getResource(name) to determine which jar/directory it came from. If the resource is not found it throws IOException 'Failed to locate the origin of <name>'. This origin URL is required to add the bootstrap classes to the parser's URLClassLoader.

Source

Thrown at independent-projects/bootstrap/maven-resolver/src/main/java/io/quarkus/bootstrap/resolver/maven/options/BootstrapMavenOptions.java:266

        } catch (ClassNotFoundException e) {
            throw e;
        } catch (Exception e) {
            throw new IllegalStateException("Failed to parse command line arguments " + Arrays.asList(args), e);
        }
    }

    /**
     * Returns the JAR or the root directory that contains the class file that is on the
     * classpath of the context classloader
     */
    public static Path getClassOrigin(Class<?> cls) throws IOException {
        return getResourceOrigin(cls.getClassLoader(), ClassLoaderHelper.fromClassNameToResourceName(cls.getName()));
    }

    public static Path getResourceOrigin(ClassLoader cl, final String name) throws IOException {
        URL url = cl.getResource(name);
        if (url == null) {
            throw new IOException("Failed to locate the origin of " + name);
        }
        String classLocation = url.toExternalForm();
        if (url.getProtocol().equals("jar")) {
            classLocation = classLocation.substring(4, classLocation.length() - name.length() - 2);
        } else {
            classLocation = classLocation.substring(0, classLocation.length() - name.length());
        }
        return urlSpecToPath(classLocation);
    }

    private static Path urlSpecToPath(String urlSpec) throws IOException {
        try {
            return Paths.get(new URL(urlSpec).toURI());
        } catch (Throwable e) {
            throw new IOException(
                    "Failed to create an instance of " + Path.class.getName() + " from " + urlSpec, e);
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Ensure quarkus-bootstrap-maven-resolver classes are loadable as resources from a plain jar or directory classpath entry
  2. When embedding, unzip the nested jar to a directory and add it to the real classpath instead of loading via a custom in-memory classloader
  3. Check the resource name derived from the class (io/quarkus/bootstrap/resolver/maven/options/BootstrapMavenOptions.class) is present in the deployed artifact
  4. Avoid shading quarkus-bootstrap classes into another jar with relocation that breaks the resource path

Example fix

// before: running from nested jar
java -jar app.jar  // BootstrapMavenOptions.class not resolvable as a resource
// after: explode and put on classpath
unzip app.jar -d app/ && java -cp "app/BOOT-INF/lib/quarkus-bootstrap-maven-resolver-*.jar:..." Main
Defensive patterns

Strategy: try-catch

Validate before calling

String resource = BootstrapMavenOptions.class.getName().replace('.', '/') + ".class";
if (BootstrapMavenOptions.class.getClassLoader().getResource(resource) == null) {
    throw new IllegalStateException("Class origin not locatable (nested/shaded jar?): " + resource);
}

Try / catch

try {
    BootstrapMavenOptions options = BootstrapMavenOptions.newInstance(cmdLine);
} catch (IllegalStateException | IOException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to locate the origin")) {
        throw new IllegalStateException("Bootstrap classes must be on a plain jar/directory classpath, not nested archive", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling BootstrapMavenOptions.newInstance()/parse() -> getClassOrigin(cls) when the class's own resource cannot be found through its classloader - e.g. the class is generated in memory, loaded by a classloader without resource access, or comes from a nested/layered archive (Spring Boot fat jar, custom launcher) where fromClassNameToResourceName lookups fail.

Common situations: Running inside an executable fat jar where quarkus-bootstrap classes are nested, custom module-layer/classloader setups in tests or app servers, shaded/relocated jars, or bootstrap classes loaded from a non-file/non-jar URL scheme.

Related errors

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