From 6b7738ce55fb425c0d3932234493e51cc81e1ab8 Mon Sep 17 00:00:00 2001 From: mason5052 Date: Mon, 1 Jun 2026 17:04:28 -0400 Subject: [PATCH 1/3] 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/3] 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 From da039383e2496535a04bfb5fca77f5e5313a9b79 Mon Sep 17 00:00:00 2001 From: mason5052 Date: Sat, 13 Jun 2026 22:52:42 -0400 Subject: [PATCH 3/3] docs: note primary image selection uses the simple agent type --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9d48a378..2173be56 100644 --- a/README.md +++ b/README.md @@ -2674,7 +2674,7 @@ See the official Docker documentation for [registry mirrors](https://docs.docker 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. +When a flow starts, PentAGI makes its first LLM call to choose the primary Docker image for the task. This image-selection call runs through the `simple` agent type, so a failure here points at the model assigned to that agent type rather than at Docker. 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. @@ -2682,7 +2682,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. +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. If you assign different models per agent type, check the model used by the `simple` agent type, since image selection runs through it. 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