alibaba/nacos · error · FileNotFoundException

Cannot create a relative resource for {getDescription()}

Error message

Cannot create a relative resource for {getDescription()}

What it means

Default AbstractResource.createRelative(String) throws FileNotFoundException because the base class cannot construct a relative resource. A concrete subclass (e.g. FileSystemResource, ClassPathResource) must override createRelative to define what 'relative to this resource' means. Hit when calling createRelative on a resource type that does not support relative paths.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/packagescan/resource/AbstractResource.java:216

     * Determine the File to use for timestamp checking.
     * The default implementation delegates to {@link #getFile()}.
     *
     * @return the File to use for timestamp checking (never {@code null})
     * @throws FileNotFoundException if the resource cannot be resolved as
     *                               an absolute file path, i.e. is not available in a file system
     * @throws IOException           in case of general resolution/reading failures
     */
    protected File getFileForLastModifiedCheck() throws IOException {
        return getFile();
    }

    /**
     * This implementation throws a FileNotFoundException, assuming
     * that relative resources cannot be created for this resource.
     */
    @Override
    public Resource createRelative(String relativePath) throws IOException {
        throw new FileNotFoundException("Cannot create a relative resource for " + getDescription());
    }

    /**
     * This implementation always returns {@code null},
     * assuming that this resource type does not have a filename.
     */
    @Override

    public String getFilename() {
        return null;
    }


    /**
     * This implementation compares description strings.
     *
     * @see #getDescription()
     */

View on GitHub (pinned to 9b989acdf1)

Solutions

Override createRelative(String) in your subclass to compute the child path (e.g. resolve against getFilename()/getFile().getParent()).
Use a concrete resource that already implements createRelative (ClassPathResource, FileSystemResource, UrlResource).
Resolve the relative path yourself (against a known base) and create a new resource directly instead of via createRelative.
Avoid calling createRelative on opaque/in-memory resources.

Example fix

// before
class BytesResource extends AbstractResource { /* only getInputStream */ }
Resource child = res.createRelative("next.json"); // FileNotFoundException

// after — use a file-backed resource that supports relative paths
Resource base = new FileSystemResource("/etc/app/config.json");
Resource child = base.createRelative("next.json");

Defensive patterns

Strategy: validation

Validate before calling

try {
    return resource.createRelative(relativePath);
} catch (FileNotFoundException e) {
    // resolve manually against a known base
    return new FileSystemResource(baseDir.resolve(relativePath).toFile());
}

Type guard

boolean supportsRelative(Resource r) {
    // concrete file/url resources override createRelative; bare AbstractResource does not
    return r instanceof FileSystemResource || r instanceof ClassPathResource
        || r instanceof UrlResource;
}

Try / catch

try {
    Resource child = resource.createRelative(rel);
} catch (FileNotFoundException e) {
    log.debug("Resource does not support relative paths: {}", e.getMessage());
}

Prevention

Use concrete resource types (FileSystemResource, ClassPathResource, UrlResource) that implement createRelative.
Override createRelative in custom AbstractResource subclasses that need relative resolution.
Resolve relative paths against a known base rather than relying on opaque resources.

When it happens

Trigger: Calling resource.createRelative("child.json") on a bare AbstractResource subclass or a custom resource that did not override createRelative; expecting relative resolution from a byte-array or opaque stream resource.

Common situations: Custom Resource wrapper used where framework code tries to resolve a sibling file; test stub of AbstractResource missing the override; passing an in-memory resource where a file-classpath sibling was expected.

Related errors

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