d2lang/d2 · critical

failed to launch Chromium: %w

Error message

failed to launch Chromium: %w

What it means

startPlaywright launches a tuned headless Chromium instance via playwright-go. If browserType.Launch fails, this error wraps the driver's message. This is the entry point for browser lifecycle (RestartBrowser, InitPlaywright, InitPlaywrightWithPrompt), so any launch failure blocks all rendering work.

Source

Thrown at lib/png/png.go:62

		return fmt.Errorf("failed to stop Playwright: %w", err)
	}
	return nil
}

func startPlaywright(pw *playwright.Playwright) (Playwright, error) {
	// Optimizations for a very tightly scoped Playwright instance
	browser, err := pw.Chromium.Launch(playwright.BrowserTypeLaunchOptions{
		Args: []string{
			"--no-sandbox",                             // Removes security overhead
			"--disable-dev-shm-usage",                  // Prevents /dev/shm issues
			"--disable-background-timer-throttling",    // Prevents CPU throttling
			"--disable-backgrounding-occluded-windows", // Keeps rendering active
			"--disable-features=TranslateUI",           // Reduces feature overhead
			"--disable-ipc-flooding-protection",        // Removes IPC limits
		},
	})
	if err != nil {
		return Playwright{}, fmt.Errorf("failed to launch Chromium: %w", err)
	}
	context, err := browser.NewContext(playwright.BrowserNewContextOptions{
		DeviceScaleFactor: playwright.Float(2.0),
	})
	if err != nil {
		return Playwright{}, fmt.Errorf("failed to start new Playwright browser context: %w", err)
	}
	page, err := context.NewPage()
	if err != nil {
		return Playwright{}, fmt.Errorf("failed to start new Playwright page: %w", err)
	}
	return Playwright{
		PW:      pw,
		Browser: browser,
		Page:    page,
	}, nil
}

View on GitHub (pinned to 0d69dca6f5)

Solutions

1. Run the Playwright browser install step (playwright-go: playwright.Run with Install option or `go run github.com/playwright-community/playwright-go/cmd/playwright install`)
2. Install OS dependencies for Chromium (libnss3, libatk, etc.) or use the official Playwright base image
3. Add container-friendly launch flags (--no-sandbox, --disable-dev-shm-usage) or run with adequate /dev/shm and memory
4. Verify driver/browser versions match your playwright-go release and inspect the wrapped driver error for the exact cause

Example fix

// before
pw, err := playwright.Run()
browser, err := browserType.Launch(opts)
// after
pw, err := playwright.Run(playwright.BrowsersPath("/ms-playwright"))
err = pw.Install() // ensure browsers present
browser, err := browserType.Launch(opts)

// Fail fast if browsers are missing
pw, err := playwright.Run()
if err != nil {
	return fmt.Errorf("playwright driver missing: %w — run playwright install", err)
}

if pw, err := InitPlaywright(); err != nil {
	if strings.Contains(err.Error(), "failed to launch Chromium") {
		// check executable exists, install browsers, then retry with backoff
	}
}

When it happens

Trigger: Chromium fails to launch: browser executable not installed (missing `playwright install`), unsupported OS/arch, missing shared libraries on the host, sandbox/permission failures in containers, or driver version mismatch.

Common situations: Fresh CI containers or slim Docker images without browser dependencies; running as root without --no-sandbox adjustments; memory limits preventing Chromium startup; upgrading playwright-go without reinstalling browsers.

Related errors

• failed to start new Playwright browser context: %w
• failed to start new Playwright page: %w
• failed to install Playwright: %w
• failed to run Playwright: %w
• failed to close Playwright browser: %w

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