karatelabs/karate · warning

Failed to write HTML report

Error message

Failed to write HTML report: {}

What it means

HtmlReportWriter.write() builds the whole HTML report (summary and per-feature pages) inside a single try block; any exception during data assembly, template rendering, or file writing is swallowed and logged as this warning. The test run is unaffected, but no (or a partial) HTML report is produced.

Solutions

1. Enable DEBUG logging for the writer to get the full stack trace ('HTML report error details') and fix the underlying exception
2. Ensure the output directory path is valid and writable before the suite starts
3. Check disk space and antivirus/file-lock interference on CI agents
4. If templates were customized, verify the classpath resources still exist under the report RESOURCE_ROOT

if (!Files.isDirectory(outputDir) && !outputDir.toFile().mkdirs()) {
    throw new IllegalStateException("cannot create report dir: " + outputDir);
}

try {
    writeReports(suiteData, features, outputDir);
} catch (Exception e) {
    logger.warn("Failed to write HTML report", e); // always log full stack when debugging
}

When it happens

Trigger: Any exception from writeReports(suiteData, features, outputDir) — missing/broken template resources, IOException writing karate-summary.html or feature pages, serialization failure on suite data, or an output directory that cannot be created.

Common situations: Read-only or non-existent output directory; disk full; custom report templates/resources removed by build filtering; NPE from unexpected FeatureResult data in custom pipelines; concurrent deletion of outputDir by a clean step.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Failed to copy static resources
• Failed to create report directories
• Failed to write feature HTML for
• Failed to write HTML summary
• Failed to externalize embeds

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/output/HtmlReportWriter.java:147

     * This is the backward-compatible entry point for direct invocation.
     *
     * @param result    the suite result to render
     * @param outputDir the directory to write reports
     * @param env       the karate environment (may be null)
     */
    public static void write(SuiteResult result, Path outputDir, String env) {
        try {
            // Build data structures from SuiteResult
            Map<String, Object> suiteData = buildSuiteData(result, env);
            List<Map<String, Object>> features = buildFeaturesList(result);

            // Generate reports
            writeReports(suiteData, features, outputDir);

            logger.debug("HTML report written to: {}", outputDir.resolve("karate-summary.html"));

        } catch (Exception e) {
            logger.warn("Failed to write HTML report: {}", e.getMessage());
            if (logger.isDebugEnabled()) {
                logger.debug("HTML report error details", e);
            }
        }
    }

    /**
     * Write a single feature HTML report.
     * Used by {@link HtmlReportListener} for async feature HTML generation.
     *
     * @param result    the feature result to render
     * @param outputDir the root output directory (features/ subdirectory will be used)
     */
    public static void writeFeatureHtml(FeatureResult result, Path outputDir) throws IOException {
        writeFeatureHtml(result, outputDir, java.util.Collections.emptyMap());
    }

    public static void writeFeatureHtml(FeatureResult result, Path outputDir,

View on GitHub (pinned to a22eb90246)