{"record":{"id":"e811c8a5711be196","repo":"chroma-core/chroma","slug":"changing-the-url-is-not-allowed","errorCode":null,"errorMessage":"Changing the URL is not allowed.","messagePattern":"Changing the URL is not allowed\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/HuggingFaceEmbeddingServerFunction.ts","lineNumber":75,"sourceCode":"    return new HuggingFaceEmbeddingServerFunction({\n      url: config.url,\n      api_key_env_var: config.api_key_env_var,\n    });\n  }\n\n  getConfig(): StoredConfig {\n    return {\n      url: this.url,\n      api_key_env_var: this.api_key_env_var,\n    };\n  }\n\n  validateConfigUpdate(\n    oldConfig: Record<string, any>,\n    newConfig: Record<string, any>,\n  ): void {\n    if (oldConfig.url !== newConfig.url) {\n      throw new Error(\"Changing the URL is not allowed.\");\n    }\n  }\n\n  validateConfig(config: Record<string, any>): void {\n    validateConfigSchema(config, \"huggingface_server\");\n  }\n}\n","sourceCodeStart":57,"sourceCodeEnd":83,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/HuggingFaceEmbeddingServerFunction.ts#L57-L83","documentation":"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.","triggerScenarios":"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.","commonSituations":"Environment promotion (staging to prod endpoint) applied to existing collections; rotating inference endpoints; DNS/hostname changes written into stored config during migration.","solutions":["Keep the URL unchanged and manage endpoint moves at the infrastructure layer (DNS alias / reverse proxy) so the configured URL stays stable","If the endpoint truly moved, create a new collection against the new URL and re-embed the source documents","Delete and recreate the collection if the existing data is disposable"],"exampleFix":"// before: repointing an existing collection's config to a new URL -> throws\n// after: new collection bound to the new endpoint\nconst ef = new HuggingFaceEmbeddingServerFunction({ url: \"https://tei-b.internal/embed\", api_key_env_var: \"HF_TOKEN\" });\nconst col2 = await client.createCollection({ name: \"docs-tei-b\", embeddingFunction: ef });\nawait col2.add({ ids, documents });","handlingStrategy":"validation","validationCode":"function assertSameUrl(oldCfg: Record<string, any>, newCfg: Record<string, any>): void {\n  if (oldCfg.url !== newCfg.url) {\n    throw new Error(`URL is immutable (${oldCfg.url} -> ${newCfg.url}); create a new collection or move the endpoint behind stable DNS`);\n  }\n}\n// call before requesting the config update","typeGuard":null,"tryCatchPattern":"try {\n  await applyConfigUpdate(collection, newCfg);\n} catch (e) {\n  if (e instanceof Error && /Changing the URL is not allowed/.test(e.message)) {\n    // endpoint moved: create a new collection and re-embed; do not retry the update\n  }\n  throw e;\n}","preventionTips":["Put a stable DNS name / reverse proxy in front of the embedding server so config URLs never need to change","Store the endpoint used at collection creation and reuse it verbatim on updates","Plan endpoint migrations as collection rebuilds (new URL = new collection + backfill)"],"tags":["config","huggingface","immutable","embeddings","validation","url"],"backgroundTag":"config-update-not-allowed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}