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, unreachable, or the URL is incorrect. Additionally, if the schema expected by the client does not match the server's schema, schema validation fails and raises this error.
Detection
Monitor connection attempts to the Weaviate server and catch ConnectionRefusedError exceptions; log schema validation results to detect mismatches before runtime failures.
Causes & fixes
Weaviate server is not running or unreachable at the specified URL
Start the Weaviate server and verify the URL and port are correct and accessible from your client environment.
Incorrect Weaviate client URL or port configuration
Double-check and correct the Weaviate client initialization URL to match the running server's address and port.
Schema mismatch between client expectations and Weaviate server schema
Synchronize the schema by updating the Weaviate server schema or adjusting the client schema definitions to match exactly.
Network firewall or proxy blocking connection to Weaviate server
Configure network rules to allow traffic on the Weaviate server port or disable interfering proxies/firewalls.
Code: broken vs fixed
import weaviate
client = weaviate.Client(url='http://localhost:8080')
# This line raises ConnectionRefusedError if server is down
schema = client.schema.get()
print(schema)import os
import weaviate
WEAVIATE_URL = os.environ.get('WEAVIATE_URL', 'http://localhost:8080')
client = weaviate.Client(url=WEAVIATE_URL) # Fixed: use env var and ensure server is running
schema = client.schema.get()
print(schema) # Successfully prints schemaWorkaround
Wrap schema calls in try/except ConnectionRefusedError, and retry connection after a delay or fallback to a cached schema if available.
Prevention
Implement health checks and connection retries before schema operations, and automate schema synchronization between client and server to avoid mismatches.