[PR #325] docs: clarify "primary docker image" error is an LLM backend failure #320

New Issue

2026-06-06T22:10:12-04:00

yindo commented

2026-06-06 22:10:12 -04:00

📋 Pull Request Information

Original PR: https://github.com/vxcontrol/pentagi/pull/325
Author: @mason5052
Created: 6/1/2026
Status: 🔄 Open

Base: main ← Head: codex/issue-309-image-chooser-troubleshooting

📝 Commits (2)

6b7738c docs: clarify "primary docker image" error is an LLM backend failure (#309)
7e51806 docs: refine LLM-backend troubleshooting wording (#309)

📊 Changes

1 file changed (+15 additions, -0 deletions)

View changed files

📝 README.md (+15 -0)

📄 Description

Summary

Add a troubleshooting subsection to the README "Docker Image Configuration" section clarifying that the failed to select primary docker image via llm call error (older versions: failed to get primary docker image) is an LLM backend failure during image selection, not a Docker or registry problem.

Refs #309

Problem

On a fresh install, creating a flow can fail immediately with:

failed to get flow provider: failed to select primary docker image via llm call: API returned unexpected status code: 502

The phrase "primary docker image" leads users to debug Docker, the image registry, or pull access even though Docker is healthy. As the maintainer noted on #309 (and on the related #312 and #203), the real cause is the configured LLM backend: PentAGI makes its first LLM call to choose the primary image when a flow starts, so a backend failure (502/404, unreachable endpoint, wrong model, or a missing/mismatched tool-call parser on custom/sglang-style backends) surfaces at this step.

The error string itself was already made more precise in #312 / #320 (failed to get primary docker image -> failed to select primary docker image via llm call). This PR closes the remaining documentation gap so users can act on that clarified message.

Solution

Add a short #### Troubleshooting subsection under "Docker Image Configuration" that:

States the error indicates an LLM backend problem, not Docker or the registry.
Explains the image-selection-at-flow-start mechanism so the origin of a 502/404 is clear.
Distinguishes it from the existing "Restricted Networks, Docker Mirrors, and Proxies" subsection, which covers genuine registry reachability.
Gives concrete diagnosis steps: check docker logs pentagi, check the LLM backend logs, verify the provider URL/key/model, and confirm tool-call / function-calling parser support for custom, OpenAI-compatible, vLLM, or sglang backends.
Cross-links to the existing "Custom LLM Provider Configuration" section.

Documentation only. No runtime, schema, config, or behavior changes.

User Impact

Users who hit this error can immediately look in the right place (the LLM backend) instead of debugging Docker, reducing time-to-resolution for a recurring fresh-install confusion reported across #309, #312, and #203.

Test Plan

Documentation-only change; no Go or frontend code touched.
git diff --check reports no whitespace errors.
Verified only README.md is modified (15 insertions).
Verified the cross-link anchor #custom-llm-provider-configuration resolves to the existing "Custom LLM Provider Configuration" heading.
Reviewed the rendered Markdown for correct heading, list, and code-span formatting.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/vxcontrol/pentagi/pull/325 **Author:** [@mason5052](https://github.com/mason5052) **Created:** 6/1/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/issue-309-image-chooser-troubleshooting` --- ### 📝 Commits (2) - [`6b7738c`](https://github.com/vxcontrol/pentagi/commit/6b7738ce55fb425c0d3932234493e51cc81e1ab8) docs: clarify "primary docker image" error is an LLM backend failure (#309) - [`7e51806`](https://github.com/vxcontrol/pentagi/commit/7e51806b8575dfa96c18642f3a5e99958bf45890) docs: refine LLM-backend troubleshooting wording (#309) ### 📊 Changes **1 file changed** (+15 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+15 -0) </details> ### 📄 Description ## Summary Add a troubleshooting subsection to the README "Docker Image Configuration" section clarifying that the `failed to select primary docker image via llm call` error (older versions: `failed to get primary docker image`) is an LLM backend failure during image selection, not a Docker or registry problem. Refs #309 ## Problem On a fresh install, creating a flow can fail immediately with: ``` failed to get flow provider: failed to select primary docker image via llm call: API returned unexpected status code: 502 ``` The phrase "primary docker image" leads users to debug Docker, the image registry, or pull access even though Docker is healthy. As the maintainer noted on #309 (and on the related #312 and #203), the real cause is the configured LLM backend: PentAGI makes its first LLM call to choose the primary image when a flow starts, so a backend failure (502/404, unreachable endpoint, wrong model, or a missing/mismatched tool-call parser on custom/sglang-style backends) surfaces at this step. The error string itself was already made more precise in #312 / #320 (`failed to get primary docker image` -> `failed to select primary docker image via llm call`). This PR closes the remaining documentation gap so users can act on that clarified message. ## Solution Add a short `#### Troubleshooting` subsection under "Docker Image Configuration" that: - States the error indicates an LLM backend problem, not Docker or the registry. - Explains the image-selection-at-flow-start mechanism so the origin of a 502/404 is clear. - Distinguishes it from the existing "Restricted Networks, Docker Mirrors, and Proxies" subsection, which covers genuine registry reachability. - Gives concrete diagnosis steps: check `docker logs pentagi`, check the LLM backend logs, verify the provider URL/key/model, and confirm tool-call / function-calling parser support for custom, OpenAI-compatible, vLLM, or sglang backends. - Cross-links to the existing "Custom LLM Provider Configuration" section. Documentation only. No runtime, schema, config, or behavior changes. ## User Impact Users who hit this error can immediately look in the right place (the LLM backend) instead of debugging Docker, reducing time-to-resolution for a recurring fresh-install confusion reported across #309, #312, and #203. ## Test Plan - Documentation-only change; no Go or frontend code touched. - `git diff --check` reports no whitespace errors. - Verified only `README.md` is modified (15 insertions). - Verified the cross-link anchor `#custom-llm-provider-configuration` resolves to the existing "Custom LLM Provider Configuration" heading. - Reviewed the rendered Markdown for correct heading, list, and code-span formatting. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

yindo added the pull-request label 2026-06-06 22:10:12 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vxcontrol/pentagi#320