Problem

When using the mem0 TypeScript SDK with Qdrant Cloud, users report an "Illegal host" error regardless of connection method — pre-configured QdrantClient, url parameter, or host+port config. Direct QdrantClient usage outside of mem0 works fine.

This traces to an upstream bug in @qdrant/js-client-rest (qdrant/qdrant-js#59) where the URL parser incorrectly handles ports in HTTPS URLs on certain methods.

The current code in mem0-ts/src/oss/src/vector_stores/qdrant.ts passes config.url directly to new QdrantClient({ url }) without any mitigation.

Solution

1. Port extraction workaround (for mem0-managed clients)

When config.url is provided, parse the port and pass it explicitly to QdrantClient alongside the URL. This bypasses the faulty URL parsing in the upstream client:

if (config.url) {
  params.url = config.url;
  try {
    const parsedUrl = new URL(config.url);
    if (parsedUrl.port) {
      params.port = parseInt(parsedUrl.port, 10);
    }
  } catch (_) {}
}

The try/catch ensures malformed URLs don't crash the constructor. Default ports (443 for HTTPS, 80 for HTTP) are not extracted since URL.port returns empty for them, preserving existing behavior.

If host+port are also provided in config, they take precedence since they're applied after the URL block.

2. JSDoc for pre-configured clients

For users passing a pre-configured QdrantClient via config.client, mem0 can't modify the client's internal state. Added JSDoc documenting that users must pass port explicitly when constructing their own client for Qdrant Cloud.

Scope & limitations

• The fix covers the case where mem0 creates the QdrantClient internally (via url config)
• For pre-configured clients, the fix is documentation-only — users must apply the workaround themselves
• The "Illegal host" error did not reproduce in our testing with @qdrant/js-client-rest@1.13.0 against Qdrant Cloud v1.17.0, suggesting the upstream bug may be version-specific. The fix is kept as defensive code to protect users on affected versions

Testing

Unit tests (8 tests) — qdrant-url-port.test.ts:

• Extracts port from HTTPS URL with explicit port (:6333)
• Extracts port from HTTP URL with explicit port
• Does not set port when URL uses default HTTPS port (443)
• Does not set port when URL uses default HTTP port (80)
• host+port config overrides URL-extracted port
• Handles invalid URL gracefully without crashing
• Skips QdrantClient constructor when pre-configured client is passed
• Handles explicit :443 in HTTPS URL (default port, URL.port returns empty)

E2E validation against a live Qdrant Cloud free-tier cluster:

• Confirmed connection + full CRUD works via url with :6333
• Confirmed connection works via url without port
• Confirmed pre-configured client with explicit port works
• Verified the upstream bug does not reproduce on current client version (v1.13.0)

Regression — full unit test suite passes (562/562 tests, 34/34 suites)

Closes #3915