.. SPDX-License-Identifier: CC-BY-4.0 .. SPDX-FileCopyrightText: Netresearch DTT GmbH .. include:: /Includes.rst.txt .. _troubleshooting: =============== Troubleshooting =============== A job that fails as a whole explains itself in the job's detail view: what happened, what is left, what the editor can do and whom to ask. The job list shows the reason in one line. An artifact that fails on its own explains itself on the artifact card; the other artifacts of the run are still produced. The explanation ends with a line to pass on, for example ``Job 13, 2026-11-01 22:38, answer_unusable``. The job number and the time find the full exception in the TYPO3 log under :file:`var/log/`; the last value is the stored reason. See :ref:`adr-011` for the reasons and why the page shows no exception text. .. _troubleshooting-answer-unusable: A job fails with "The AI answer could not be used" ================================================== The reason is ``answer_unusable``, and the log holds ``Failed to decode JSON response: Syntax error``. The text model gave an answer that is no JSON object, twice: the extension asks once more with twice the room. An empty answer reads as this syntax error too. A reasoning model counts its thinking against the token limit, and at a limit near the length of the answer it can return nothing at all, with finish reason ``length``. From nr-llm 0.43.2 on the log names this case: ``The model reached its output limit before it wrote an answer``. Check the ``Max tokens`` field of the ``nr_repurpose_text`` configuration (see :ref:`configuration-nr-llm`). A value below 16,000 is raised per call, and ``0`` leaves the choice to the model. .. _troubleshooting-queued: The job stays "queued" ====================== Submitting a job only dispatches a message; a worker does the generation. A job that never leaves ``queued`` means no worker consumes the transport the message is routed to. - Check that the generation message is routed to the ``doctrine`` transport (see :ref:`configuration-messenger`). - Run a consumer for that transport, and keep it running (see :ref:`installation-worker`): .. code-block:: bash :caption: Consume the generation transport vendor/bin/typo3 messenger:consume doctrine - To run one job without the worker, for example while debugging, use ``vendor/bin/typo3 nr_repurpose:generate ``. .. _troubleshooting-vault: The job fails in "analyzing" with a denied secret ================================================= The error reads like this, and no artifact is produced: ``Access denied to secret "…": insufficient permissions`` The worker and the CLI command run as an unauthenticated command-line user, and nr-vault refuses every secret read without an actor. Set :confval:`technicalBeUserUid ` to a backend user that may read the provider key's secret: a user with access to the secret through its owner or its groups, or an administrator as long as nr-vault's administrator override is not disabled. .. _troubleshooting-renderer: Schaubild or story images fail with "HTML render failed" ======================================================== The artifact error reads ``HTML render failed (exit …)``. The renderer's error output is in the TYPO3 log, in the entry ``HTML render failed`` with the exit code and ``stderr``. The images are rendered by ``node`` running the bundled ``render.cjs``, which starts Chromium. - ``node`` must be on the worker's ``PATH``. - The Chromium binary must exist at the renderer's Chromium path, default ``/usr/bin/chromium`` (see :ref:`configuration-rendering`). - The renderer's own dependency must be installed (see :ref:`installation-node-renderer`). The slide deck and the handout are printed by the same renderer and fail the same way. .. _troubleshooting-ffmpeg: The podcast or the story video fails with an ffmpeg error ========================================================= The artifact error contains ``ffmpeg concat failed (exit …)`` or ``ffprobe failed (exit …)`` for the podcast, or ``ffmpeg slideshow failed (exit …)`` for the story video. ``ffmpeg`` and ``ffprobe`` must be on the worker's ``PATH``. .. _troubleshooting-source-url: A URL job fails with "Source URL …" =================================== The worker fetches a *Webpage URL* or *PDF URL* source only over ``http`` or ``https`` and only from a host outside the local and internal network. It refuses any other URL before the request, and the job fails with one of these errors: - ``Source URL scheme "…" is not allowed, only http and https: …`` - ``Source URL has no host: …`` - ``Source URL host … is a numeric IPv4 spelling; write the address as four decimal numbers (a.b.c.d)`` - ``Source URL host does not resolve: …`` - ``Source URL host … resolves to a loopback, private, link-local or reserved address`` — the host, or one of the addresses it resolves to, lies in the local or internal network. The address itself is written to the TYPO3 log, not to the error. - ``Source URL cannot be parsed: …`` — the HTTP library cannot read the URL. Where an error names the URL, it shows scheme, host, port and path only: a user name and password, the query and the fragment are left out, because every user of the module sees the error. A value that is not a URL with a scheme and a host shows as ``(URL not shown)``. The job list, the result view, the social planning, the prompts sent to the text model and the story, slide deck and handout show the URL the same way. The social webhook receives it without user name and password but with its query and fragment. The job keeps the URL as entered, and the job record in the List module shows it whole. No setting allows an internal host. For a PDF that only an internal server provides, choose the file as a *PDF file (FAL)* source. A page of this installation is a *Page of this site* source, which reads its own site on any address. The worker does not follow redirects, because a redirect target would bypass this check. A redirecting URL fails with ``URL returned HTTP 301: …`` or ``PDF URL returned HTTP 302: …`` (or another 3xx status); enter the URL the redirect points to. .. _troubleshooting-page-source: A page job fails or leaves pages out ==================================== The result view lists what a page job left out. A failed job names the reason: - ``None of the … selected pages could be read: …`` — the worker could not load any page; the message names the first failure. A page must answer 200 at its public URL without a redirect and without HTTP authentication, and the worker must reach the site's host. ``Page … has no public URL`` means the page belongs to no site, or its site base names no host and the job does not know one. With ``base: /`` the job uses the host of the backend it was created on, and a private address is refused as for a URL source: set an absolute base in the site configuration. - ``Page … and its subpages hold no page a visitor can open`` — the selection has become hidden, restricted or empty since the job was created. - ``The job owner may not read page …`` or ``The job owner may not read the attached PDF: …`` — the user who created the job has lost access. ``A page source needs a job owner with an enabled backend user`` — that user is disabled or deleted. .. _troubleshooting-source-limits: A URL job fails with "Source is larger than …" or "Source did not arrive within …" ================================================================================== The worker reads a web page up to 5 MiB within 30 seconds and downloads a PDF up to 50 MiB within 120 seconds. The limits are fixed. - ``Source is larger than 5 MiB: …`` (``50 MiB`` for a PDF) — the source is larger than the limit. Choose a larger PDF as a *PDF file (FAL)* source instead. - ``Source did not arrive within 30 seconds: …`` (``120 seconds`` for a PDF) — the server did not deliver the source in time. - ``Reading the source failed: …`` — the transfer broke off while the body was read. ``Fetching a remote source needs the PHP extension curl`` — the worker fetches a source only through curl, which connects to the addresses the host was checked with. Install the PHP extension ``curl`` on the host that runs the worker (see :ref:`installation-requirements`). .. _troubleshooting-poppler: A PDF job fails with "pdftoppm failed" or "pdftotext -layout failed" ==================================================================== The PDF modes ``vision`` and ``tables``, and ``auto`` for sparse or tabular pages, call the poppler tools ``pdftoppm`` and ``pdftotext``. Install ``poppler-utils`` on the host that runs the worker. ``No text could be extracted from the PDF`` means that no tier returned any text; ``PDF could not be parsed (possibly encrypted or damaged)`` means the file could not be opened. .. _troubleshooting-not-permitted: An artifact fails with "Not permitted" ====================================== The error names the missing option, ``nrrepurpose:generate_audio`` or ``nrrepurpose:generate_vision``. The backend groups of the user who created the job do not grant it. Grant it in the group's custom module options (see :ref:`configuration-permissions`). Reading a PDF with Vision OCR needs ``nrrepurpose:generate_vision`` as well. Without it a page keeps its embedded text and the job continues. A PDF that has no embedded text at all fails the whole job with this error: ``The PDF has no embedded text, and reading it with Vision OCR is not permitted: the job owner's backend groups do not grant "Generate AI imagery" (nrrepurpose:generate_vision)`` .. _troubleshooting-budget: An artifact fails with "AI budget used up, or the service is not available" =========================================================================== The stored reason is ``budget_or_service``. Either the job creator's nr-llm budget does not cover the planned cost, or nr-llm's speech or image service is not available, for example because the ``nr_repurpose_tts`` or ``nr_repurpose_image`` configuration or its provider is missing (see :ref:`configuration-nr-llm`). The Schaubild's plain HTML variant needs neither and is still produced. .. _troubleshooting-memory: The worker dies while compositing images ======================================== PHP's ``memory_limit`` must be higher than the ``--memory-limit`` passed to ``messenger:consume``, with room for GD image compositing. Otherwise PHP stops the process before Messenger can restart it, and the message is delivered again into the same crash. See :ref:`installation-worker`.