ConnectionRefusedError
weaviate.exceptions.ConnectionRefusedError
Stack trace
weaviate.exceptions.ConnectionRefusedError: Failed to connect to Weaviate server at 'http://localhost:8080'. Connection refused. During schema validation: Schema mismatch or missing class detected.
Why it happens
This error occurs when the Weaviate client cannot establish a network connection to the Weaviate server, often because the server is down, the endpoint URL is incorrect, or firewall rules block access. Additionally, if the expected schema class is missing or mismatched, the client raises an error during schema validation.
Detection
Monitor connection attempts to the Weaviate endpoint and catch ConnectionRefusedError exceptions. Log schema validation steps to detect missing or incorrect schema classes before runtime failures.
Causes & fixes
Weaviate server is not running or unreachable at the specified endpoint.
Start the Weaviate server and verify the endpoint URL and port are correct and accessible from your client environment.
Incorrect or missing schema class in Weaviate database for your RAG vector store.
Define and apply the correct schema class in Weaviate matching your vector store requirements before connecting.
Network firewall or proxy blocking connection to Weaviate server.
Configure firewall or proxy settings to allow traffic on the Weaviate server port (default 8080).
Using HTTP instead of HTTPS or vice versa causing connection refusal.
Ensure the protocol in the endpoint URL matches the Weaviate server configuration (http:// or https://).
Code: broken vs fixed
import weaviate
client = weaviate.Client(url='http://localhost:8080')
# This line triggers connection refused error if server is down
schema = client.schema.get()import os
import weaviate
WEAVIATE_URL = os.environ.get('WEAVIATE_URL', 'http://localhost:8080')
client = weaviate.Client(url=WEAVIATE_URL) # Use env var for flexibility
# Confirm connection before schema call
try:
schema = client.schema.get()
print('Connected and schema retrieved successfully')
except weaviate.exceptions.ConnectionRefusedError as e:
print(f'Connection failed: {e}')
# Handle or retry connection hereWorkaround
Catch ConnectionRefusedError and implement a retry loop with exponential backoff to wait for Weaviate server availability before proceeding.
Prevention
Automate Weaviate server health checks and schema validation during deployment pipelines to ensure the server is running and schema is correct before client usage.