From 6b7738ce55fb425c0d3932234493e51cc81e1ab8 Mon Sep 17 00:00:00 2001 From: mason5052 Date: Mon, 1 Jun 2026 17:04:28 -0400 Subject: [PATCH 1/2] docs: clarify "primary docker image" error is an LLM backend failure (#309) Add a troubleshooting subsection to the Docker Image Configuration section explaining that "failed to select primary docker image via llm call" (older versions: "failed to get primary docker image") is raised when PentAGI's first LLM call fails during image selection, not when Docker or the registry is unhealthy. Points users to PentAGI and LLM backend logs, provider URL/key/model verification, and tool-call parser configuration for custom/OpenAI-compatible/vLLM/sglang backends. --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index fc5ca587..97ff585c 100644 --- a/README.md +++ b/README.md @@ -2670,6 +2670,21 @@ On Linux, this is typically configured in `/etc/docker/daemon.json`. On Docker D See the official Docker documentation for [registry mirrors](https://docs.docker.com/docker-hub/image-library/mirror/) and [daemon proxy configuration](https://docs.docker.com/engine/daemon/proxy/). +#### Troubleshooting: "failed to select primary docker image via llm call" + +A flow that fails immediately with `failed to select primary docker image via llm call` usually indicates a problem with the configured LLM backend, not with Docker or the image registry. Older PentAGI versions reported the same failure as `failed to get primary docker image`, which led users to debug Docker even though the registry was healthy. + +When a flow starts, PentAGI makes its first LLM call to choose the primary Docker image for the task. If that call fails, the error is surfaced at this image-selection step. A message such as `API returned unexpected status code: 502` or `404` in this context is returned by the LLM backend, not by Docker Hub. + +This is distinct from the registry reachability problems described above: if Docker pulls succeed and the Compose stack starts, but flow creation still fails at image selection, investigate the LLM backend rather than Docker. + +To diagnose: + +1. Check PentAGI logs first: `docker logs pentagi`. +2. Check the logs of your configured LLM backend (the server behind your provider or `LLM_SERVER_URL`). +3. Verify that the base URL, API key, and model name in [Custom LLM Provider Configuration](#custom-llm-provider-configuration) are correct and reachable from the container. +4. For custom, OpenAI-compatible, vLLM, or sglang backends, confirm that the model supports tool calling / function calling and that the matching tool-call parser is enabled. A missing or mismatched tool-call parser is a known cause of this failure. + ## Development ### Development Requirements From 7e51806b8575dfa96c18642f3a5e99958bf45890 Mon Sep 17 00:00:00 2001 From: mason5052 Date: Mon, 1 Jun 2026 17:25:58 -0400 Subject: [PATCH 2/2] docs: refine LLM-backend troubleshooting wording (#309) Address review feedback on PR #325: capitalize SGLang to match the project's name and clarify that tool calling and function calling refer to the same capability. Refs #309 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 97ff585c..9d48a378 100644 --- a/README.md +++ b/README.md @@ -2683,7 +2683,7 @@ To diagnose: 1. Check PentAGI logs first: `docker logs pentagi`. 2. Check the logs of your configured LLM backend (the server behind your provider or `LLM_SERVER_URL`). 3. Verify that the base URL, API key, and model name in [Custom LLM Provider Configuration](#custom-llm-provider-configuration) are correct and reachable from the container. -4. For custom, OpenAI-compatible, vLLM, or sglang backends, confirm that the model supports tool calling / function calling and that the matching tool-call parser is enabled. A missing or mismatched tool-call parser is a known cause of this failure. +4. For custom, OpenAI-compatible, vLLM, or SGLang backends, confirm that the model supports tool calling (function calling) and that the matching tool-call parser is enabled. A missing or mismatched tool-call parser is a known cause of this failure. ## Development