karatelabs/karate · error · ResourceNotFoundException

cannot find resource

Error message

cannot find resource: {path}

What it means

Resource.path() resolves a classpath-style path by searching the context and system classloaders. When the relative path cannot be found on the classpath (both lookups return null), it throws ResourceNotFoundException with 'cannot find resource: {path}'. This signals the resource is not on the runtime classpath — a lookup failure, not a read failure.

Solutions

  1. Verify the exact path spelling and that the file lives under src/main/resources or src/test/resources
  2. Rebuild so resources are copied to target/classes / target/test-classes
  3. Use the classpath-relative path without leading slash or 'classpath:' duplication as the API expects
  4. List the jar/target/classes to confirm the resource was packaged

Example fix

// before
Resource.path("classpath:fixtures/missing-data.json")
// after (file moved to src/test/resources/fixtures/data.json)
Resource.path("classpath:fixtures/data.json")
Defensive patterns

Strategy: validation

Validate before calling

// Java: verify resource presence on the classpath before Resource.path
String rel = "fixtures/data.json";
if (Thread.currentThread().getContextClassLoader().getResource(rel) == null
        && ClassLoader.getSystemResource(rel) == null) {
    throw new IllegalStateException("not on classpath: " + rel);
}

Try / catch

try {
    Resource r = Resource.path("classpath:fixtures/data.json");
} catch (ResourceNotFoundException e) {
    logger.error("classpath resource missing: {}", e.getMessage());
    // fail fast with build/packaging guidance
}

Prevention

When it happens

Trigger: Calling Resource.path('classpath:...') with a path that is not packaged in the jar or under target/classes; typo in the resource path; resource excluded by build filters; running from an IDE/module where the resources directory isn't on the classpath.

Common situations: Test fixture under src/test/resources not yet copied to target/test-classes (build not run); resource renamed during a refactor; resource filtered out by Maven resource filtering excludes; classpath differs between IDE and Maven runs.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/1f7a4f5c2331ed19. Report an issue: GitHub.

Appendix: source

Thrown at karate-js/src/main/java/io/karatelabs/common/Resource.java:573

                relativePath = relativePath.substring(1);
            }

            // Try provided classloader, then context classloader, then system classloader
            URL url = null;
            if (classLoader != null) {
                url = classLoader.getResource(relativePath);
            }
            if (url == null) {
                ClassLoader contextCL = Thread.currentThread().getContextClassLoader();
                if (contextCL != null) {
                    url = contextCL.getResource(relativePath);
                }
            }
            if (url == null) {
                url = ClassLoader.getSystemResource(relativePath);
            }
            if (url == null) {
                throw new ResourceNotFoundException(path);
            }
            // Convert URL to Path for classpath resources
            try {
                Path resourcePath = urlToPath(url, null);
                return new PathResource(resourcePath, FileUtils.WORKING_DIR.toPath(), true);
            } catch (java.nio.file.ProviderNotFoundException e) {
                // JAR file system provider not available (common in jpackage/JavaFX apps)
                // Fall back to streaming the resource content (root defaults to SYSTEM_TEMP)
                try (java.io.InputStream is = url.openStream()) {
                    String content = FileUtils.toString(is);
                    return new MemoryResource(content);
                } catch (Exception ex) {
                    throw new RuntimeException("Failed to create resource from classpath: " + path, ex);
                }
            } catch (Exception e) {
                throw new RuntimeException("Failed to create resource from classpath: " + path, e);
            }
        } else if (path.startsWith(FILE_COLON)) {

View on GitHub (pinned to a22eb90246)