Why is Weaviate not working?

Common reasons Weaviate stops working: (1) the Weaviate Cloud service is down — check prismix.dev/service/weaviate; (2) wrong API URL or missing API key; (3) vector dimensions mismatch between your embeddings and the collection schema; (4) gRPC connection errors (default port 50051 not open); (5) out-of-memory on a self-hosted instance; (6) collection does not exist or class name case mismatch.

Weaviate connection refused — how to fix?

Connection refused to Weaviate usually means: (1) Weaviate is not running — start with docker run -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:latest; (2) wrong port — REST API is 8080, gRPC is 50051; (3) firewall blocking inbound connections; (4) for Weaviate Cloud, check your cluster URL ends with .weaviate.network and the cluster is not paused.

Weaviate vector dimensions mismatch error — what causes it?

Vector dimensions mismatch happens when the embedding model you use at query time produces vectors of a different size than those stored in the collection. For example, if you indexed with text-embedding-3-small (1536 dims) but query with text-embedding-ada-002 (also 1536 dims) that is fine; but switching to text-embedding-3-large (3072 dims) will fail. Fix: delete the collection and re-index with the new model, or keep the same model throughout.

Weaviate 401 / 403 authentication error

Authentication errors in Weaviate: (1) for Weaviate Cloud, pass the API key via the X-Weaviate-Api-Key header or the auth_client_secret parameter in the client; (2) for self-hosted with API key auth enabled, add AUTHENTICATION_APIKEY_ENABLED=true and AUTHENTICATION_APIKEY_ALLOWED_KEYS in docker-compose; (3) if you enabled anonymous access but it stopped working, check AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED is still true.

Weaviate gRPC errors with Python client v4

Weaviate Python client v4 uses gRPC (port 50051) by default for better performance. If you get gRPC connection errors: (1) expose port 50051 in Docker: -p 50051:50051; (2) for Weaviate Cloud, use the grpc_port parameter (typically 443 for TLS); (3) if gRPC is not available, fall back to HTTP-only mode: client = weaviate.connect_to_wcs(cluster_url=url, auth_credentials=..., skip_init_checks=True, grpc_url=None) — or use weaviate.use_async_with_weaviate_cloud with grpc disabled.

Weaviate 5 min read

Weaviate Not Working? Fix Common Errors

Troubleshoot Weaviate errors — connection refused, vector dimensions mismatch, 401 authentication, gRPC port 50051 issues — for both self-hosted and Weaviate Cloud.

Weaviate Cloud — live status

Updated every 5 minutes · Full incident history →

Full status →

Common errors and fixes

Connection refused (self-hosted)

The most common issue with self-hosted Weaviate is not exposing the correct ports. Weaviate uses two ports:

REST API

port 8080

CRUD, schema, batch

gRPC (v4 client)

port 50051

Query, search (faster)

docker run -d \
  -p 8080:8080 \
  -p 50051:50051 \
  -e QUERY_DEFAULTS_LIMIT=25 \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
  cr.weaviate.io/semitechnologies/weaviate:latest

Vector dimensions mismatch

Weaviate stores the vector size at collection creation time. Switching embedding models without re-indexing causes this error.

How to diagnose: Check the collection schema to see the configured vector dimensions:

import weaviate

client = weaviate.connect_to_local()
collection = client.collections.get("MyCollection")
print(collection.config.get().properties)
# Check vector_index_config for dimensions

Fix: Delete the collection and recreate it with the new model's dimensions. There is no in-place migration.

401 / 403 — Authentication error

For Weaviate Cloud (WCD), authentication uses an API key:

import weaviate
import weaviate.classes.init as wvc

client = weaviate.connect_to_weaviate_cloud(
    cluster_url="https://your-cluster.weaviate.network",
    auth_credentials=wvc.Auth.api_key("YOUR-WCD-API-KEY"),
)

# Or using environment variable (recommended):
# WCD_URL=https://your-cluster.weaviate.network
# WCD_API_KEY=YOUR-WCD-API-KEY

Get your API key from console.weaviate.cloud → Cluster Details → API Keys
Admin key vs Read-only key — use Admin key for indexing, Read-only for query-only services
For self-hosted: set AUTHENTICATION_APIKEY_ENABLED=true in env

gRPC errors with Python client v4

The Weaviate Python client v4 uses gRPC by default. If port 50051 is not open, you'll see connection errors. Two options:

Option A: open port 50051 (recommended)

docker run -p 8080:8080 -p 50051:50051 cr.weaviate.io/...

Option B: disable gRPC (REST-only fallback)

client = weaviate.connect_to_local(
    port=8080,
    grpc_port=None,   # disables gRPC
)

Out-of-memory (self-hosted)

Weaviate loads vector indexes into RAM. A collection of 1 million 1536-dim float32 vectors requires ~6 GB of RAM. If your instance runs out of memory:

Check memory usage: GET /v1/nodes returns memory stats per node
Switch to disk-based index: set vectorIndexType: flat with pq quantization — uses much less RAM
Enable compression: Product Quantization (PQ) or Binary Quantization (BQ) reduces memory 4–32×
Weaviate Cloud: scales automatically — no manual memory management needed

Class / collection not found

Weaviate class names are case-sensitive and must start with a capital letter. Common mistakes:

✖ Wrong

collection = "articles"
collection = "Articles2024"

✔ Correct

collection = "Articles"
collection = "Article2024"

List all collections: client.collections.list_all()

🔔

Know when Weaviate Cloud has an outage

Free email alerts. Star Weaviate on Prismix — no credit card needed.

View status Sign in free →

FAQ

Weaviate vs Pinecone — which is more reliable?

Both are production-grade vector databases. Weaviate is open-source and can be self-hosted; Pinecone is fully managed. For uptime comparison, check prismix.dev/service/weaviate and prismix.dev/service/pinecone.

Weaviate slow query performance

Slow queries usually mean the HNSW index has high ef (search effort). For faster but slightly less accurate results, lower ef in query params. Also ensure HNSW index build is complete before querying — querying during indexing degrades both.

Can I use Weaviate without an embedding model?

Yes — Weaviate supports "bring your own vectors" (vectorizer: none in the schema). Pass pre-computed vectors directly when upserting objects. You can also use Weaviate's built-in vectorizer modules (OpenAI, Cohere, HuggingFace) to handle embedding automatically.

Monitor related services

Pinecone

OpenAI API (embeddings)

Anthropic / Claude

Groq

Weaviate status → Pinecone not working → OpenAI API status → All AI status → All guides →