How to troubleshoot Open WebUI provider connection errors

Open WebUI provider errors usually appear as an empty model selector, a failed Verify Connection alert, a slow model refresh, or a chat request that never reaches the model server. The fastest fix is to prove where the request breaks, because a provider URL can work from the host shell while failing from the Open WebUI container.

Provider connections depend on the API protocol and the network location of the Open WebUI backend. OpenAI-compatible providers normally expose a base URL ending in /v1, while Ollama exposes its own API on port 11434. When Open WebUI runs in Docker, localhost and 127.0.0.1 point at the container itself, not at a model server running on the host.

Work from the provider outward, then retest the original Open WebUI symptom. A corrected base URL should answer from the Open WebUI runtime, survive a model-list refresh, and complete one short chat with the model that was previously missing or failing.

1. Copy the provider base URL from the failing Open WebUI connection.

   Use the base URL, not a full model-list URL. For an OpenAI-compatible server, copy a value such as http://127.0.0.1:8000/v1. For Ollama, copy a value such as http://127.0.0.1:11434.

2. Probe the provider from the machine where it is running.

   $ curl --fail-with-body --silent --show-error "http://127.0.0.1:8000/v1/models"
   {"object":"list","data":[{"id":"company-chat","object":"model","owned_by":"company"},{"id":"company-vision","object":"model","owned_by":"company"}]}

   For providers that require authentication, add the provider's authorization header for this probe. For Ollama, request http://127.0.0.1:11434/api/tags instead of the OpenAI-compatible /v1/models path.
   Tool: API Testing Tool

3. Probe the same host-local URL from the Open WebUI container.

   $ docker exec open-webui curl --fail-with-body --silent --show-error --connect-timeout 3 "http://127.0.0.1:8000/v1/models"
   curl: (7) Failed to connect to 127.0.0.1 port 8000 after 0 ms: Couldn't connect to server

   This failure means the provider answers on the host, but Open WebUI is trying to reach 127.0.0.1 inside its own container.

4. Replace the saved host-local base URL with a URL the Open WebUI runtime can reach.

   http://host.docker.internal:8000/v1

   Use http://host.docker.internal:11434 for Ollama on the Docker Desktop host, a container DNS name such as http://ollama:11434 when both services share a Docker network, or the model server's reachable LAN or service address. On Linux without Docker Desktop, the Docker run or compose file may need a host.docker.internal host-gateway mapping before that name resolves.

5. Probe the corrected URL from the Open WebUI container.

   $ docker exec open-webui curl --fail-with-body --silent --show-error "http://host.docker.internal:8000/v1/models"
   {"object":"list","data":[{"id":"company-chat","object":"model","owned_by":"company"},{"id":"company-vision","object":"model","owned_by":"company"}]}

6. Save the corrected provider URL in Admin Settings → Connections and run Verify Connection.

   Keep the provider API key out of screenshots, tickets, shell history, and shared logs. A wrong key can still fail after the URL is fixed, but the network probe should answer before spending time on credential rotation.

7. Refresh the Open WebUI model list and confirm the expected model appears.

   If model loading remains slow, disable or remove any leftover unreachable provider URLs before testing again; Open WebUI waits for configured endpoints when it builds the combined model list.
   Related: How to refresh the Open WebUI model list

8. Send a short chat prompt with the refreshed model and confirm that the reply appears in Open WebUI.

   If the model list works but chat fails, check the provider's chat endpoint, model ID, and API key scope next; the base URL problem is fixed once Open WebUI can list the provider models from its runtime.