ConnectionRefusedError
builtins.ConnectionRefusedError
Stack trace
Traceback (most recent call last):
File "app.py", line 10, in <module>
response = client.chat.completions.create(model="llama2", messages=messages)
File "/usr/local/lib/python3.9/site-packages/ollama/client.py", line 45, in create
raise ConnectionRefusedError("Connection refused on localhost:11434")
builtins.ConnectionRefusedError: Connection refused on localhost:11434 Why it happens
This error occurs because the Ollama local server is not running or not listening on port 11434, so the client cannot establish a TCP connection. It can also happen if a firewall or network policy blocks the connection or if the port is occupied by another process.
Detection
Monitor connection attempts to localhost:11434 and catch ConnectionRefusedError exceptions when initializing the Ollama client to detect server unavailability early.
Causes & fixes
Ollama local server is not started or crashed
Start the Ollama server locally before running the client code, ensuring it listens on port 11434.
Port 11434 is blocked by firewall or security software
Configure firewall or security settings to allow inbound and outbound connections on port 11434.
Another process is occupying port 11434
Identify and stop the conflicting process or configure Ollama to use a different available port.
Client is configured to connect to wrong host or port
Verify the client configuration points to localhost and port 11434 exactly, correcting any typos or environment variable errors.
Code: broken vs fixed
import ollama
response = ollama.chat(model="llama2", messages=[{"role": "user", "content": "Hello"}]) # ConnectionRefusedError hereimport ollama
response = ollama.chat(model="llama2", messages=[{"role": "user", "content": "Hello"}])
print(response) # Fixed: server must be runningWorkaround
Wrap the client call in try/except ConnectionRefusedError, and retry connection after a delay or alert the user to start the Ollama server manually.
Prevention
Implement health checks to verify the Ollama server is running before client requests and automate server startup in your deployment or development environment.