karatelabs/karate · error · RuntimeException

embed(): failed to read part path

Error message

embed(): failed to read part path '{path}': {message}

What it means

Karate's embed() JS bridge reads each part's path from disk via readPathBytes() in KarateJsBase. When resolving or reading the stream fails (missing file, bad scheme prefix, IO error), the raw exception is wrapped in this RuntimeException so the failing path and underlying message are surfaced to script authors.

Solutions

1. Verify the path exists relative to the feature file / current resource and fix typos
2. Check the URI prefix: use this: for feature-relative, classpath: for packaged resources, file: for absolute paths
3. Ensure classpath resources are actually on the test classpath (target/test-classes, jar packaging)
4. Inspect the wrapped cause message ({message}) for the underlying IO error and fix permissions or disk issues

Example fix

// before
embed('screenshots/login.png')
// after
// file is feature-relative, or generate it before embedding
var path = 'classpath:reports/login.png';
if (karate.readIfExists) { /* or ensure the file exists */ }
embed('this:reports/login.png');

function fileExists(p) { return java.nio.file.Files.exists(java.nio.file.Paths.get(p)); } // or karate.readIfExists for classpath

try { embed(path); } catch (e) { karate.log('embed failed for ' + path + ': ' + e.message); }

When it happens

Trigger: Calling embed(path) (or embed with multiple parts) in JS where a part path cannot be resolved by the current Resource against getCurrentResource().resolve(path), or whose InputStream cannot be opened/read: nonexistent file, wrong this:/classpath:/file: prefix, unreadable file, or empty/corrupt target.

Common situations: Typos in the report-embed path; embedding a classpath resource that was never packaged into the jar/test classpath; using a relative path when the working directory differs between local runs and CI; file moved after generation (e.g. screenshot not yet written).

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• readAsStream() needs at least one argument
• Failed to open stream for:
• embed() needs at least one argument: data
• embed(): each 'parts' entry must be an object
• embed(): each part needs a 'role'

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateJsBase.java:562

            } else if (pathObj != null) {
                bytes = readPathBytes(pathObj.toString());
            } else {
                throw new RuntimeException("embed(): part '" + role + "' needs 'data', 'path', or 'url'");
            }
            parts.add(new StepResult.Part(role, mime != null ? mime : KarateJsUtils.detectMimeType(bytes), bytes));
        }
        Object meta = map.get("meta");
        @SuppressWarnings("unchecked")
        Map<String, Object> metaMap = meta instanceof Map ? (Map<String, Object>) meta : null;
        return new StepResult.Embed(name, parts, metaMap);
    }

    /** Read an embed part's {@code path} (this:/classpath:/file:/relative) into bytes. */
    private byte[] readPathBytes(String path) {
        try (java.io.InputStream is = getCurrentResource().resolve(path).getStream()) {
            return is.readAllBytes();
        } catch (Exception e) {
            throw new RuntimeException("embed(): failed to read part path '" + path + "': " + e.getMessage(), e);
        }
    }

    /** Unwrap a JsValue (e.g. a nested Uint8Array / object) to its idiomatic Java value. */
    private static Object unwrapJs(Object o) {
        return o instanceof JsValue jv ? jv.getJavaValue() : o;
    }

    /**
     * karate.signal() - Signal a result for listen/listenResult.
     */
    JavaInvokable signal() {
        return args -> {
            ScenarioRuntime rt = getRuntime();
            if (rt != null && args.length > 0) {
                rt.setListenResult(args[0]);
            }
            return null;

View on GitHub (pinned to a22eb90246)