{"record":{"id":"45d392e6caaf7ddb","repo":"karatelabs/karate","slug":"boot-read-file-not-found-path-root-is-root-a-leading-anchors","errorCode":null,"errorMessage":"boot.read: file not found: ${path} (root is ${root} — a leading '/' anchors the project root, 'file:' is a host path; declare boot.classpath(dir) to map 'classpath:' refs)","messagePattern":"boot\\.read: file not found: (.+?) \\(root is (.+?) — a leading '/' anchors the project root, 'file:' is a host path; declare boot\\.classpath\\(dir\\) to map 'classpath:' refs\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/BootBinding.java","lineNumber":191,"sourceCode":"     * anchors THE project root, a bare ref is root-relative, {@code classpath:} is\n     * classloader-first then the {@link #classpath(String)} fallback, and {@code file:} is a host\n     * path. Declare {@code boot.classpath(...)} before reading a {@code classpath:} ref that is\n     * not on the real classpath.\n     */\n    public String read(String path) {\n        if (path == null) throw new IllegalArgumentException(\"boot.read: path is null\");\n        java.nio.file.Path classpathRoot = classpathDir == null || root == null\n                ? root : root.resolve(classpathDir).normalize();\n        try {\n            Resource r = Resource.path(path, root, classpathRoot);\n            if (r.exists()) {\n                return r.getText();\n            }\n            throw new RuntimeException(\"boot.read: file not found: \" + path\n                    + \" (resolved to \" + r + \"; root is \" + root\n                    + \" — a leading '/' anchors the project root, 'file:' is a host path)\");\n        } catch (io.karatelabs.common.ResourceNotFoundException e) {\n            throw new RuntimeException(\"boot.read: file not found: \" + path\n                    + \" (root is \" + root + \" — a leading '/' anchors the project root, \"\n                    + \"'file:' is a host path; declare boot.classpath(dir) to map 'classpath:' refs)\", e);\n        }\n    }\n\n    /** {@code boot.log('...')} — INFO log with [boot] prefix. */\n    public void log(Object msg) {\n        logger.info(\"[boot] {}\", msg == null ? \"null\" : msg.toString());\n    }\n\n    /**\n     * {@code boot.ext('name')} — resolve + construct + register an ext.\n     *\n     * <p>Resolution by name convention: {@code 'openapi'} →\n     * {@code io.karatelabs.ext.openapi.OpenapiExt}. The class is loaded from\n     * the runtime classloader; missing ext → boot-time failure (suite fails loud).</p>\n     *\n     * <p>Same name twice returns the same singleton instance.</p>","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/BootBinding.java#L173-L209","documentation":"boot.read(path) attempted to resolve the path (e.g. a classpath: ref) and the underlying Resource resolution raised ResourceNotFoundException, which is converted into a RuntimeException explaining that the file was not found, what the root is, and that boot.classpath(dir) must be declared to map classpath: refs into a project directory. Unlike the plain not-found variant, this indicates resolution itself failed (typically a classpath: ref with no classpath root available).","triggerScenarios":"boot.read('classpath:foo/bar.json') where the ref is not on the real classpath and boot.classpath(dir) was not declared (or classpathRoot resolution failed); a path that Resource.path cannot resolve to an existing location.","commonSituations":"Forgetting boot.classpath(...) before reading classpath: files kept only under src/test/resources; running in a context where the resource was never packaged into the jar; classpath dir mapping pointing at the wrong folder.","solutions":["Declare boot.classpath('src/test/resources') (or the correct dir) before the boot.read call.","Put the resource on the real test classpath so classpath: resolution succeeds.","Switch to a root-relative bare path or 'file:' path if the resource is not meant to be a classpath resource.","Confirm the classpath dir mapping actually contains the file."],"exampleFix":"// before\nboot.read('classpath:mocks/certs.pem'); // ResourceNotFoundException\n// after\nboot.classpath('src/test/resources');\nboot.read('classpath:mocks/certs.pem');","handlingStrategy":"validation","validationCode":"// before reading a classpath: ref at boot\nboot.classpath('src/test/resources'); // ensure mapping exists first\n// and confirm the file is present in that dir","typeGuard":null,"tryCatchPattern":"try {\n    var text = boot.read('classpath:mocks/data.json');\n} catch (RuntimeException e) {\n    // fall back to a root-relative path or fail with a clear setup message\n}","preventionTips":["Always pair classpath: boot.read calls with an earlier boot.classpath(dir) declaration.","Or place resources in a directory that is genuinely on the test classpath.","Keep a checklist of boot declarations at the top of the boot script."],"tags":["boot","classpath","file-not-found"],"backgroundTag":"file-not-found","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}