What causes "Failed to write HTML summary: {}" in karatelabs/karate?

Check the logged exception message to identify the failed write path.

Failed to write HTML summary

Error message

Failed to write HTML summary: {}

What it means

WARN log from HtmlReportListener.onSuiteEnd when generating the suite-level HTML summary (including the timeline page) throws an exception. All tests have already run; only the final HTML summary artifacts are missing or incomplete. The exception message is logged and swallowed.

Solutions

Check the logged exception message to identify the failed write path.
Re-run report generation after fixing the output directory, or re-run the suite with a writable outputDir.
Free disk space if the volume is full.
Avoid deleting/locking the report directory (browsers, sync tools, CI cleaners) while the suite runs.

Defensive patterns

Strategy: try-catch

Try / catch

// suite-end failures don't propagate; verify the summary artifact afterwards
File summary = new File(reportDir, "karate-summary.html");
if (!summary.exists()) logger.warn("HTML summary missing — check 'Failed to write HTML summary' log");

Prevention

Don't open/delete the summary HTML in a browser or sync tool while the suite is running.
Ensure sufficient disk space before suite end when many features are aggregated.
Treat a missing karate-summary.html after a run as a signal to inspect this warning.

When it happens

Trigger: Exception while writing summary/timeline HTML in onSuiteEnd — usually an I/O error writing into outputDir (read-only, deleted, disk full), or an error building the summary/timeline data from feature maps.

Common situations: Output directory cleaned up or locked while the suite was running; disk exhaustion at suite end; file-lock contention from the summary page opened in a browser during the run; permission changes mid-run.

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

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/output/HtmlReportListener.java:194

    }

    @Override
    public void onSuiteEnd(SuiteResult result) {
        try {
            // Ensure resources are copied
            ensureResourcesCopied();

            // Write summary pages using canonical feature maps
            List<Map<String, Object>> summaryCards = suite != null ? suite.getSummaryCards() : java.util.Collections.emptyList();
            HtmlReportWriter.writeSummaryPages(featureMaps, result, outputDir, env, reportAssets, summaryCards);

            // Write timeline page using canonical feature maps
            HtmlReportWriter.writeTimelineHtml(featureMaps, result, outputDir, env, threadCount, reportAssets);

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

        } catch (Exception e) {
            logger.warn("Failed to write HTML summary: {}", e.getMessage());
        }
    }

    private synchronized void ensureResourcesCopied() {
        if (!resourcesCopied) {
            try {
                HtmlReportWriter.copyStaticResources(outputDir.resolve("res"));
                resourcesCopied = true;
            } catch (Exception e) {
                logger.warn("Failed to copy static resources: {}", e.getMessage());
            }
        }
    }

}

View on GitHub (pinned to a22eb90246)