{"record":{"id":"16a9576d766a7652","repo":"matplotlib/matplotlib","slug":"error-starting-mpl-rcparams-pgf-texsystem-r","errorCode":null,"errorMessage":"Error starting {mpl.rcParams['pgf.texsystem']!r}","messagePattern":"Error starting (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"lib/matplotlib/backends/backend_pgf.py","lineNumber":303,"sourceCode":"\n    def _setup_latex_process(self, *, expect_reply=True):\n        # Open LaTeX process for real work; register it for deletion.  On\n        # Windows, we must ensure that the subprocess has quit before being\n        # able to delete the tmpdir in which it runs; in order to do so, we\n        # must first `kill()` it, and then `communicate()` with or `wait()` on\n        # it.\n        try:\n            self.latex = subprocess.Popen(\n                [mpl.rcParams[\"pgf.texsystem\"], \"-halt-on-error\", \"-no-shell-escape\"],\n                stdin=subprocess.PIPE, stdout=subprocess.PIPE,\n                encoding=\"utf-8\", cwd=self.tmpdir)\n        except FileNotFoundError as err:\n            raise RuntimeError(\n                f\"{mpl.rcParams['pgf.texsystem']!r} not found; install it or change \"\n                f\"rcParams['pgf.texsystem'] to an available TeX implementation\"\n            ) from err\n        except OSError as err:\n            raise RuntimeError(\n                f\"Error starting {mpl.rcParams['pgf.texsystem']!r}\") from err\n\n        def finalize_latex(latex):\n            latex.kill()\n            try:\n                latex.communicate()\n            except RuntimeError:\n                latex.wait()\n\n        self._finalize_latex = weakref.finalize(\n            self, finalize_latex, self.latex)\n        # write header with 'pgf_backend_query_start' token\n        self._stdin_writeln(self._build_latex_header())\n        if expect_reply:  # read until 'pgf_backend_query_start' token appears\n            self._expect(\"*pgf_backend_query_start\")\n            self._expect_prompt()\n\n    def get_width_height_descent(self, text, prop):","sourceCodeStart":285,"sourceCodeEnd":321,"githubUrl":"https://github.com/matplotlib/matplotlib/blob/b379c1b69e012b142c0f496a52bcb30513802d72/lib/matplotlib/backends/backend_pgf.py#L285-L321","documentation":"Companion to the FileNotFoundError case in _setup_latex_process: any other OSError from subprocess.Popen when starting pgf.texsystem (permission denied, target not executable, resource/spawn limits) is re-raised as RuntimeError(f'Error starting {…!r}') with the original exception chained via __cause__.","triggerScenarios":"pgf.texsystem pointing at a file that exists but lacks the execute bit, a broken wrapper script, a noexec-mounted filesystem holding the TeX binaries, or a security layer (SELinux/AppArmor) denying exec.","commonSituations":"Manually copied TeX binaries without +x; TeX installed on a network mount or container volume mounted noexec; corrupted installations where the binary fails immediately.","solutions":["Inspect the chained exception: except RuntimeError as e: print(e.__cause__) to see the real OSError","Ensure the binary is executable: chmod +x $(which pdflatex)","Check that the filesystem holding the TeX bin dir is not mounted noexec","Reinstall the TeX distribution if the binary itself is damaged"],"exampleFix":"# before: rcParams['pgf.texsystem'] points at /opt/tex/bin/xelatex without +x\n#   -> RuntimeError: Error starting 'xelatex'\n\n# after\n# chmod +x /opt/tex/bin/xelatex   (or use the distro-packaged engine on PATH)","handlingStrategy":"validation","validationCode":"import os\nimport shutil\nimport matplotlib as mpl\n\ndef texsystem_runnable() -> bool:\n    exe = shutil.which(mpl.rcParams['pgf.texsystem'])\n    return exe is not None and os.access(exe, os.X_OK)\n\nif not texsystem_runnable():\n    raise SystemExit('pgf.texsystem is missing or not executable')","typeGuard":null,"tryCatchPattern":"try:\n    fig.savefig('out.pgf')\nexcept RuntimeError as err:\n    if 'Error starting' not in str(err):\n        raise\n    raise RuntimeError('cannot start TeX engine') from err.__cause__  # real OSError","preventionTips":["Ensure TeX binaries carry the execute bit (chmod +x) especially after manual copies","Avoid installing TeX on noexec-mounted volumes","Inspect err.__cause__ — it carries the underlying OSError and errno"],"tags":["matplotlib","pgf","latex","subprocess","permissions","spawn"],"backgroundTag":"process-spawn-failed","analyzedSha":"b379c1b69e012b142c0f496a52bcb30513802d72","analyzedAt":"2026-08-21T23:31:55.468Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}