Chroma Collection Initialization Failure in Docker

Collection creation succeeds (returns 200 OK), but immediate Get or Query operations fail with 400 Bad Request errors. Issue occurs consistently in Docker Compose but not in local/embedded deployments. Error messages may indicate collection not found or invalid collection reference despite successful creation moments before.

1. Diagnose network configuration: Check Docker Compose network settings — ensure client and server are on same network. Verify hostname resolution: client should use service name defined in docker-compose.yml, not localhost. Check port mappings: ensure host:container port mappings are consistent with client configuration. 2. Verify API endpoint consistency: Client connection URL should match service name and port: `http://chroma-server:8000` not `http://localhost:8000` when in container. Check environment variables: CHROMA_HOST, CHROMA_PORT must match service definition. Verify no host.docker.internal misuse (Windows/Mac specific). 3. Test connectivity: From client container, test server reachability: `curl http://chroma-server:8000/api/v1/heartbeat`. Check DNS resolution: `nslookup chroma-server` should resolve to service IP. Verify no firewall or network policy blocking inter-service communication. 4. Simplify configuration: Remove abstraction layers (Synapse SDK, custom wrappers) and test with direct Chroma client. Isolate whether issue is Chroma-specific or wrapper-specific. Test with minimal docker-compose.yml: single client container, single server container. 5. Check timing/consistency: Add retry logic with backoff after collection creation before querying. Some deployments show eventual consistency where collection becomes available after brief delay. 6. Review logs: Check Chroma server logs for incoming requests — verify requests are reaching server. Check for authentication/authorization errors. Look for network timeout or connection refused errors.