Skip to content

docs: clarify "primary docker image" error is an LLM backend failure #325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mason5052 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: clarify "primary docker image" error is an LLM backend failure #325

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6b7738c
docs: clarify "primary docker image" error is an LLM backend failure …
mason5052 Jun 1, 2026
7e51806
docs: refine LLM-backend troubleshooting wording (#309)
mason5052 Jun 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Comment thread
mason5052 marked this conversation as resolved.

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
Expand Down