watch mode: cannot watch non-file resource

Error message

watch mode: cannot watch non-file resource: {} (classpath resources in JARs are not watchable)

What it means

Mock server watch/reload mode was enabled, but one of the loaded features comes from a Resource that is not a local file (e.g. packaged inside a JAR on the classpath). File-modification-based watching is impossible for such resources, so Karate logs a warning and skips watching that feature; it will be served but never hot-reloaded.

Solutions

Pass file-system paths (File or the feature file directly on disk) instead of classpath resources to the mock server builder.
Extract/copy the features to a local directory before starting the mock server and watch that directory.
Disable watch/reload mode if hot reload is not needed — the warning is otherwise harmless.
Run with an exploded classpath (target/classes, target/test-classes) rather than a JAR during development.

Example fix

// before
MockServer.feature("classpath:mock/feature.feature").watch(true).build()
// after
MockServer.feature("src/test/resources/mock/feature.feature").watch(true).build()

Defensive patterns

Strategy: validation

Validate before calling

Resource r = feature.getResource();
if (!r.isLocalFile()) throw new IllegalStateException("watch mode needs local file, got: " + r.getRelativePath());

Prevention

Load features from file-system paths when using watch mode.
Run mocks from an exploded classpath during development.
Only enable watch mode in dev profiles, never in packaged deployments.

When it happens

Trigger: Starting MockServer with reload/watch enabled while passing features loaded via classpath: references that resolve to entries inside JARs, or any resource where resource.isLocalFile() is false.

Common situations: Running mocks against a fat JAR or shaded build; features bundled in a test-jar dependency; IDE running with features copied to a build output JAR; Docker image containing features inside an app JAR.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/MockServer.java:394

        private final boolean javaBridgeEnabled;
        private final boolean requestExpressionsEnabled;
        private final Map<Resource, Long> watchedFiles = new LinkedHashMap<>();
        private MockHandler handler;

        ReloadingHandler(List<Feature> features, Map<String, Object> args, String pathPrefix, boolean javaBridgeEnabled, boolean requestExpressionsEnabled) {
            this.args = args;
            this.pathPrefix = pathPrefix;
            this.javaBridgeEnabled = javaBridgeEnabled;
            this.requestExpressionsEnabled = requestExpressionsEnabled;

            // Track file modification times for each feature
            for (Feature feature : features) {
                Resource resource = feature.getResource();
                if (resource.isLocalFile()) {
                    watchedFiles.put(resource, resource.getLastModified());
                    logger.debug("watching file: {} (modified: {})", resource.getRelativePath(), resource.getLastModified());
                } else {
                    logger.warn("watch mode: cannot watch non-file resource: {} (classpath resources in JARs are not watchable)",
                            resource.getRelativePath());
                }
            }

            if (watchedFiles.isEmpty()) {
                logger.warn("watch mode enabled but no watchable files found - features may be from classpath JARs");
            }

            // Initialize handler
            handler = new MockHandler(features, args, pathPrefix, javaBridgeEnabled, requestExpressionsEnabled);
        }

        MockHandler getHandler() {
            return handler;
        }

        @Override
        public HttpResponse apply(HttpRequest request) {

View on GitHub (pinned to a22eb90246)