{"record":{"id":"007d952fa0f6553e","repo":"karatelabs/karate","slug":"doc-requires-a-string-path-or-map-with-read-key-got","errorCode":null,"errorMessage":"doc requires a string path or map with 'read' key, got: ","messagePattern":"doc requires a string path or map with 'read' key, got: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/StepExecutor.java","lineNumber":2993,"sourceCode":"        } else {\n            expr = step.getText();\n            runtime.eval(expr, step);\n        }\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private void executeDoc(Step step) {\n        String text = step.getText();\n        Object value = runtime.eval(wrapJsonLikeExpression(text));\n        // karate.doc() expects either a string path or a map with 'read' key\n        // Convert string to the expected format\n        String html;\n        if (value instanceof String path) {\n            html = runtime.getKarate().doc(Map.of(\"read\", path));\n        } else if (value instanceof Map) {\n            html = runtime.getKarate().doc((Map<String, Object>) value);\n        } else {\n            throw new RuntimeException(\"doc requires a string path or map with 'read' key, got: \" + value);\n        }\n        // Embed the rendered HTML in the step result for reports\n        if (html != null && !html.isEmpty()) {\n            LogContext.get().embed(html.getBytes(java.nio.charset.StandardCharsets.UTF_8), \"text/html\");\n        }\n    }\n\n    // ========== Config ==========\n\n    private void executeConfigure(Step step) {\n        String text = step.getText();\n        int eqIndex = StepUtils.findAssignmentOperator(text);\n        if (eqIndex < 0) {\n            throw new RuntimeException(\"configure requires '=' assignment: \" + text);\n        }\n        String key = text.substring(0, eqIndex).trim();\n        String expr = text.substring(eqIndex + 1).trim();\n        if (expr.isEmpty() && step.getDocString() != null) {","sourceCodeStart":2975,"sourceCodeEnd":3011,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/StepExecutor.java#L2975-L3011","documentation":"The `doc` keyword renders HTML (e.g. from a Markdown file) for embedding into reports. Its argument must be either a String path (wrapped internally as {read: path}) or a Map containing at least a 'read' key. Any other type (number, list, null-coerced object) cannot be processed and this error names the offending value.","triggerScenarios":"`doc <expr>` where expr evaluates to a non-string/non-map value, e.g. a JSON array, integer, or a JS object that is not a plain Map; forgetting the map form: `doc { badKey: 'x' }` still passes the Map branch but doc itself will need 'read'.","commonSituations":"Using doc with a variable that was meant to be text but resolved to parsed JSON; copy-pasting examples and dropping the read key; dynamic doc paths built into lists.","solutions":["Pass a plain string path: `doc classpath:doc.md` or a quoted path variable","Pass a map with a 'read' key: `doc { read: '#(path)' }`","print the value type before the doc step to verify","Coerce with string concatenation if the value is a number/other scalar"],"exampleFix":"// before\n* def meta = { file: 'notes.md' }\n* doc meta\n// after\n* doc { read: '#(meta.file)' }","handlingStrategy":"validation","validationCode":"* if (!(docArg instanceof String || docArg.read)) karate.fail('doc arg must be string path or {read: ...} map')","typeGuard":"function isValidDocArg(v) { return typeof v === 'string' || (v && typeof v === 'object' && 'read' in v); }","tryCatchPattern":null,"preventionTips":["Use the string path form for the common case","Always include a 'read' key in the map form","print value types when building doc args dynamically"],"tags":["doc","type-mismatch","report"],"backgroundTag":"invalid-argument-format","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}