What causes "PDF renderer failed to initialize." in srbhr/Resume-Matcher?

Check earlier server logs for the underlying Playwright launch failure (missing executable, launch timeout)

srbhr/Resume-Matcher · error · PDFRenderError

PDF renderer failed to initialize.

Error message

PDF renderer failed to initialize.

What it means

PDFRenderError raised in render_resume_pdf when the module-level lazy-initialized `_browser` is still None after the init path ran, meaning the renderer never successfully started. It guards the render call against using an uninitialized Playwright browser instance.

Solutions

Check earlier server logs for the underlying Playwright launch failure (missing executable, launch timeout)
Run `<python> -m playwright install chromium` in the deployment environment
Restart the backend so lazy init retries on the next request
Add retry/init-failure propagation around the browser initialization step
Ensure only the app's event loop policy allows subprocesses (_loop_supports_subprocess) so init can run on Windows

Defensive patterns

Strategy: retry

Validate before calling

from app import pdf
def renderer_ready() -> bool:
    return pdf._browser is not None

Try / catch

try:
    pdf_bytes = await render_resume_pdf(url, selector)
except PDFRenderError as e:
    if str(e) == "PDF renderer failed to initialize.":
        await asyncio.sleep(1)
        pdf_bytes = await render_resume_pdf(url, selector)  # retry re-runs lazy init
    else:
        raise

Prevention

Check deploy logs for the browser-install step succeeding before serving traffic
Wrap lazy init with explicit error propagation instead of leaving _browser None
Warm up the renderer at startup with a probe render
Serialize init so concurrent first requests don't race the launch
On Windows ensure the subprocess-friendly event loop policy is set

When it happens

Trigger: render_resume_pdf is called but `_browser` remains None because the lazy init (get/launch browser) failed or was skipped, and the failure path didn't already raise a more specific error.

Common situations: First PDF request arriving before/while browser initialization failed; Playwright runtime missing browsers in a fresh deploy; init exception swallowed in the init helper; concurrent requests racing an in-progress init that failed.

Related errors

AI-assisted analysis of srbhr/Resume-Matcher@116f9cc3b0 (2026-08-28). Data as JSON: /api/errors/50e32abcb8724a4b. Report an issue: GitHub.

Appendix: source

Thrown at apps/backend/app/pdf.py:333

        try:
            await init_pdf_renderer()
        except NotImplementedError:
            async with _subprocess_lock:
                _subprocess_supported = False
            subprocess_supported = False
        except PlaywrightError as e:
            _raise_playwright_error(e, url)

    if not subprocess_supported:
        try:
            return await _render_resume_pdf_in_thread(
                url, selector, pdf_format, pdf_margins
            )
        except PlaywrightError as e:
            _raise_playwright_error(e, url)

    if _browser is None:
        raise PDFRenderError("PDF renderer failed to initialize.")

    try:
        return await _render_with_browser(_browser, url, selector, pdf_format, pdf_margins)
    except PlaywrightError as e:
        _raise_playwright_error(e, url)

View on GitHub (pinned to 116f9cc3b0)