chroma-core/chroma · error · ChromaValueError

Invalid URL: ${path}

Error message

Invalid URL: ${path}

What it means

parseConnectionPath (utils.ts:764-780) runs new URL(path) on the deprecated ChromaClient `path` argument (chroma-client.ts:103-111, which also logs a deprecation warning recommending host/port/ssl). The WHATWG URL constructor requires an absolute URL with a scheme; if it cannot parse the input, the catch block rethrows ChromaValueError 'Invalid URL: <path>'.

Source

Thrown at clients/new-js/packages/chromadb/src/utils.ts:778

    throw new ChromaValueError("Number of requested results has to positive");
  }
};

export const parseConnectionPath = (path: string) => {
  try {
    const url = new URL(path);

    const ssl = url.protocol === "https:";
    const host = url.hostname;
    const port = url.port;

    return {
      ssl,
      host,
      port: Number(port),
    };
  } catch {
    throw new ChromaValueError(`Invalid URL: ${path}`);
  }
};
const packEmbedding = (embedding: number[]): ArrayBuffer => {
  const buffer = new ArrayBuffer(embedding.length * 4);
  const view = new Float32Array(buffer);
  for (let i = 0; i < embedding.length; i++) {
    view[i] = embedding[i];
  }
  return buffer;
};

export const embeddingsToBase64Bytes = (embeddings: number[][]) => {
  return embeddings.map((embedding) => {
    const buffer = packEmbedding(embedding);

    const uint8Array = new Uint8Array(buffer);
    const binaryString = Array.from(uint8Array, (byte) =>
      String.fromCharCode(byte),

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Use the non-deprecated options: new ChromaClient({ host: 'localhost', port: 8000, ssl: false })
2. If you must use path, always include the scheme: 'http://localhost:8000' or 'https://...'
3. Pre-validate with URL.canParse(path) (or a try/catch around new URL(path)) before constructing the client

Example fix

// before
new ChromaClient({ path: 'localhost:8000' });

// after
new ChromaClient({ host: 'localhost', port: 8000 });
// or, if path is required: new ChromaClient({ path: 'http://localhost:8000' })

// Node 18.17+/browsers: URL.canParse
if (path && !URL.canParse(path)) {
  throw new Error(`connection path must be an absolute URL like 'http://host:8000', got: ${path}`);
}
const client = new ChromaClient({ path });
// better: avoid the deprecated path option entirely
new ChromaClient({ host: 'localhost', port: 8000, ssl: false });

const isAbsoluteHttpUrl = (v: unknown): v is string =>
  typeof v === 'string' && /^https?:\/\/.+/.test(v);

try {
  client = new ChromaClient({ path });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid URL:')) {
    client = new ChromaClient({ path: `http://${path}` }); // add the missing scheme and retry
  } else throw e;
}

When it happens

Trigger: new ChromaClient({ path: 'localhost:8000' }) (no scheme); path: 'chroma.example.com'; path: 'http//host:8000' (typo); path: ''.

Common situations: Building the connection string from environment variables that lack the http:// prefix; migrating older code that used `path` instead of the host/port/ssl options.

Related errors

• Changing the URL is not allowed.
• Expected metadata to be non-empty
• Expected metadata list value for key '${key}' to be non-empt
• Expected metadata list value for key '${key}' to contain onl
• Expected metadata list value for key '${key}' to contain onl

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/8f77ad8e4f5eeee2. Report an issue: GitHub.