Troubleshooting

Start with the logs of both sides of a connection: docker compose logs -f pentagi for PentAGI and the logs of your model backend or proxy.

A flow fails with "failed to select primary docker image via llm call"

The first thing a flow does is ask the model to choose a Docker image, through the simple agent type. This error almost always points at the model backend, not at Docker:

1. Check the PentAGI logs and your model backend's logs.
2. Verify the base URL, API key and model name are correct and reachable from the container.
3. This call sends no tools, so it fails on the connection, the key or the model, not on tool calling: check that the simple agent's model answers a plain chat request. A missing tool-call parser shows up later, once agents start calling tools.

Tool-call parser errors with self-hosted models

PentAGI drives agents with tool calls, so a custom backend must return valid OpenAI-style tool-call JSON. Symptoms of a missing or mismatched parser include Failed to parse tool call arguments as JSON, flows that stop after a few steps, and tool calls that loop without converging.

• Enable the tool-call parser and chat template recommended for the model you serve in llama.cpp, SGLang or vLLM.
• Validate the provider with the ctester utility before running a full flow.
• Update PentAGI: recent builds sanitize malformed arguments so one bad response no longer stalls a flow.

macOS flags the installer

The macOS builds are signed and notarized. If macOS still warns about the installer, do not override it with Open Anyway: delete the file and download the archive for your CPU again from the official links — darwin/amd64 for Intel, darwin/arm64 for Apple silicon. Never reuse an archive from an unofficial source.

Smaller models get stuck

Enable execution monitoring and task planning and give the adviser agent a stronger model or a higher reasoning setting.

Still stuck?

Ask in Discord or open an issue with the relevant log lines.