d2lang/d2 · error

issue encountered with PNG exporter: %w

Error message

issue encountered with PNG exporter: %w

What it means

In watch mode, when the output is a PNG or PDF, compilation uses a headless browser managed by Playwright. If the browser is disconnected, watch tries RestartBrowser(); if that fails, the error is wrapped as "issue encountered with PNG exporter" and broadcast to connected viewers.

Source

Thrown at d2cli/watch.go:430

func (w *watcher) compileLoop(ctx context.Context) error {
	firstCompile := true
	for {
		select {
		case <-w.compileCh:
		case <-ctx.Done():
			return ctx.Err()
		}

		recompiledPrefix := ""
		if !firstCompile {
			recompiledPrefix = "re"
		}

		if (filepath.Ext(w.outputPath) == ".png" || filepath.Ext(w.outputPath) == ".pdf") && !w.pw.Browser.IsConnected() {
			newPW, err := w.pw.RestartBrowser()
			if err != nil {
				broadcastErr := fmt.Errorf("issue encountered with PNG exporter: %w", err)
				w.ms.Log.Error.Print(broadcastErr)
				w.broadcast(&compileResult{
					Err: broadcastErr.Error(),
				})
				continue
			}
			w.pw = newPW
		}

		fs := trackedFS{}
		w.boardpathMu.Lock()
		var boardPath []string
		if w.boardPath != "" {
			boardPath = strings.Split(w.boardPath, string(os.PathSeparator))
		}
		svg, _, err := compile(ctx, w.ms, w.plugins, &fs, w.layout, w.renderOpts, w.fontFamily, w.monoFontFamily, w.animateInterval, w.inputPath, w.outputPath, boardPath, false, w.bundle, w.forceAppendix, w.pw.Browser, w.outputFormat, w.asciiMode)
		w.boardpathMu.Unlock()
		errs := ""

View on GitHub (pinned to 0d69dca6f5)

Solutions

1. Install/reinstall the Playwright browser binaries that D2 relies on
2. Run the container/host with required Chromium dependencies (or --no-sandbox where appropriate)
3. Restart the watch session to get a fresh browser process

Example fix

// before
d2 file.d2 --watch --format png   # chromium missing
// after
# install browser deps first, then
d2 file.d2 --watch --format png

// before watching:
if _, err := exec.LookPath(browserBinary); err != nil {
	// install Playwright browser dependencies first
}

if result.Err != "" && strings.Contains(result.Err, "PNG exporter") {
	// restart watch or switch output format to svg
}

When it happens

Trigger: compileLoop detects output extension .png or .pdf with w.pw.Browser.IsConnected() == false, and the attempted RestartBrowser() returns an error (browser binary missing, failed launch, display/sandbox issues).

Common situations: Playwright/Chromium not installed or downloaded, running in a container without required shared libraries, headless environment missing --no-sandbox, browser process crashed (OOM) during a long watch session.

Related errors

• failed to close Playwright browser: %w
• failed to fully %scompile (rendering partial svg): %w
• failed to %scompile: %w
• failed to stop Playwright: %w
• failed to launch Chromium: %w

AI-assisted analysis of d2lang/d2@0d69dca6f5 (2026-08-31). Data as JSON: /api/errors/ddeae1cf52a93272. Report an issue: GitHub.