chroma-core/chroma · error · Error

Changing the URL is not allowed.

Error message

Changing the URL is not allowed.

What it means

HuggingFaceEmbeddingServerFunction pins the server URL for the lifetime of an embedding configuration: validateConfigUpdate() throws whenever oldConfig.url differs from newConfig.url. Vectors already in the collection came from that specific server/model deployment, so silently repointing it would mix embedding spaces and corrupt search results.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/HuggingFaceEmbeddingServerFunction.ts:75

    return new HuggingFaceEmbeddingServerFunction({
      url: config.url,
      api_key_env_var: config.api_key_env_var,
    });
  }

  getConfig(): StoredConfig {
    return {
      url: this.url,
      api_key_env_var: this.api_key_env_var,
    };
  }

  validateConfigUpdate(
    oldConfig: Record<string, any>,
    newConfig: Record<string, any>,
  ): void {
    if (oldConfig.url !== newConfig.url) {
      throw new Error("Changing the URL is not allowed.");
    }
  }

  validateConfig(config: Record<string, any>): void {
    validateConfigSchema(config, "huggingface_server");
  }
}

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Keep the URL unchanged and manage endpoint moves at the infrastructure layer (DNS alias / reverse proxy) so the configured URL stays stable
2. If the endpoint truly moved, create a new collection against the new URL and re-embed the source documents
3. Delete and recreate the collection if the existing data is disposable

Example fix

// before: repointing an existing collection's config to a new URL -> throws
// after: new collection bound to the new endpoint
const ef = new HuggingFaceEmbeddingServerFunction({ url: "https://tei-b.internal/embed", api_key_env_var: "HF_TOKEN" });
const col2 = await client.createCollection({ name: "docs-tei-b", embeddingFunction: ef });
await col2.add({ ids, documents });

function assertSameUrl(oldCfg: Record<string, any>, newCfg: Record<string, any>): void {
  if (oldCfg.url !== newCfg.url) {
    throw new Error(`URL is immutable (${oldCfg.url} -> ${newCfg.url}); create a new collection or move the endpoint behind stable DNS`);
  }
}
// call before requesting the config update

try {
  await applyConfigUpdate(collection, newCfg);
} catch (e) {
  if (e instanceof Error && /Changing the URL is not allowed/.test(e.message)) {
    // endpoint moved: create a new collection and re-embed; do not retry the update
  }
  throw e;
}

When it happens

Trigger: An embedding-config update where newConfig.url differs — e.g. migrating from one TEI deployment (https://tei-a.internal/embed) to another (https://tei-b.internal/embed) on an existing collection, or a template injecting a different host.

Common situations: Environment promotion (staging to prod endpoint) applied to existing collections; rotating inference endpoints; DNS/hostname changes written into stored config during migration.

Related errors

• The model name cannot be changed after initialization.
• The task type cannot be changed after initialization.
• Cannot change model name.
• Config is missing a required field
• Failed to generate embeddings: ${response.statusText}

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