alibaba/nacos · error · FileNotFoundException

{getDescription()} cannot be opened because it does not exis

Error message

{getDescription()} cannot be opened because it does not exist

What it means

ClassPathResource.getInputStream() resolves the resource via the class loader, the owning Class, or the system loader in turn, and throws FileNotFoundException (with a human-readable description) when every loader returns null. It indicates the configured path simply is not present on the classpath at runtime.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/packagescan/resource/ClassPathResource.java:199

    /**
     * This implementation opens an InputStream for the given class path resource.
     *
     * @see ClassLoader#getResourceAsStream(String)
     * @see Class#getResourceAsStream(String)
     */
    @Override
    public InputStream getInputStream() throws IOException {
        InputStream is;
        if (this.clazz != null) {
            is = this.clazz.getResourceAsStream(this.path);
        } else if (this.classLoader != null) {
            is = this.classLoader.getResourceAsStream(this.path);
        } else {
            is = ClassLoader.getSystemResourceAsStream(this.path);
        }
        if (is == null) {
            throw new FileNotFoundException(getDescription() + " cannot be opened because it does not exist");
        }
        return is;
    }

    /**
     * This implementation returns a URL for the underlying class path resource,
     * if available.
     *
     * @see ClassLoader#getResource(String)
     * @see Class#getResource(String)
     */
    @Override
    public URL getUrl() throws IOException {
        URL url = resolveUrl();
        if (url == null) {
            throw new FileNotFoundException(getDescription() + " cannot be resolved to URL because it does not exist");
        }
        return url;

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Verify the resource physically exists inside the deployed JAR (`jar tf app.jar | grep <path>`) or on the classpath directory.
  2. Correct the path: drop or add a leading `/` depending on whether you want class-relative or loader-relative resolution; normalize separators to `/`.
  3. If using a fat/shaded JAR, adjust the assembly or shade plugin to include the resource file in the build output.
  4. Pass an explicit Class or ClassLoader whose visibility covers the resource instead of relying on the system loader fallback.

Example fix

// before — path does not exist on classpath
Resource r = new ClassPathResource("config/app.yml");
InputStream in = r.getInputStream(); // throws

// after — correct path under classpath root
Resource r = new ClassPathResource("META-INF/config/app.yml");
Defensive patterns

Strategy: validation

Validate before calling

static InputStream openIfExists(ClassPathResource r) throws IOException {
    if (!r.exists()) {
        throw new FileNotFoundException(
            "Missing classpath resource: " + r.getPath() + " — verify packaging/path");
    }
    return r.getInputStream();
}

Try / catch

try {
    InputStream in = resource.getInputStream();
} catch (FileNotFoundException fnf) {
    // log the description, fall back to a default resource, or fail fast
    throw fnf;
}

Prevention

When it happens

Trigger: Constructing a ClassPathResource with a path that the JVM classloader cannot locate, then calling getInputStream(). The path is resolved relative to the class root; a leading slash or wrong separator changes the lookup root and can cause a miss.

Common situations: Loading a bundled config or certificate from a JAR whose packaging (shade/assembly) excluded or relocated the file. Referencing `com/example/foo.properties` when the resource sits under `META-INF/`. Running in a fat-jar or module layer where the resource is on a non-delegated loader. Typo in the path, or a leading `/` that shifts the lookup from class-relative to classloader-relative.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/efa44301c4ff1f30. Report an issue: GitHub.