fix(embeddings): correct width sizing, Ollama width resolution, and family gating

Round of review findings:

- Size the shared indexing batch for the widest storable width; the aggregate
  guard rejects rather than splits, so a 3,072-wide base past 1,064 chunks failed
- Resolve an unstated Ollama width from the server instead of defaulting to 1,536
- Substitute EMBEDDING_OUTPUT_DIMS alongside the model when evaluating the
  knowledge-embedding capability, so the chain is judged for the target at hand
- Classify the embedding family exactly as the runtime does, so an id the runtime
  rejects cannot report its family as configured
- Validate a capability field against the provider being configured, not the first
  one declaring the key, which rejected 384 in the Ollama wizard branch
- Give OpenRouter the OpenAI-family model and width fields it was missing
- Resolve model records by own property, so KB_EMBEDDING_MODEL=toString falls back
- Narrow a knowledge base's width only for query searches, not tag-only ones
- Report an unreachable Ollama as 502 rather than a missing model
- Correct the sim-setup command and scope, the Ollama filtering claims, and the
  unstorable-width troubleshooting advice in the docs

Author: icecrasher321

apps/docs/content/docs/integrations/embeddings.mdx

@@ -19,15 +19,15 @@ Models differ in what they are good at and what they cost. `text-embedding-3-sma
 
 Two things worth knowing before you build on it. Vectors are only comparable when they come from the same model at the same size, so changing either means re-embedding everything you intend to compare. And input longer than the model's limit is shortened to fit rather than rejected, with a warning in the run, so chunk long documents yourself when the tail matters.
 
-Ollama is the exception to most of the above. It runs on your own deployment, so it needs no API key and costs nothing, and the model list is whatever you have pulled onto that server rather than a catalog Sim maintains — the block reads it live, filters it to models that can actually embed, and shows each one's vector width next to its name. Ollama accepts neither a task type nor a size reduction, so the block does not offer those controls for it. Self-hosted deployments configure the server with `OLLAMA_URL`; on Sim Cloud there is no Ollama to reach, so the list comes back empty.
+Ollama is the exception to most of the above. It runs on your own deployment, so it needs no API key and costs nothing, and the model list is whatever you have pulled onto that server rather than a catalog Sim maintains — the block reads it live, drops the models that report a non-embedding capability, and shows each one's vector width next to its name where Ollama reports one. A server too old to report either will list its chat models too and label none of them, so check the model you pick. Ollama accepts neither a task type nor a size reduction, so the block does not offer those controls for it. Self-hosted deployments configure the server with `OLLAMA_URL`; on Sim Cloud there is no Ollama to reach, so the list comes back empty.
 
 Sim's knowledge bases embed separately: a base fixes one model and one vector width when it is created, from a smaller set of models. This block is for embedding text yourself inside a workflow.
 {/* MANUAL-CONTENT-END */}
 
 
 ## Usage Instructions
 
-Turn text into embedding vectors for semantic search, clustering, and similarity. Supports OpenAI, OpenRouter, Google Gemini, Cohere, and Mistral embedding models, plus any model on a self-hosted Ollama.
+Turn text into embedding vectors for semantic search, clustering, and similarity. Supports OpenAI, OpenRouter, Google Gemini, Cohere, and Mistral embedding models, plus embedding models on a self-hosted Ollama.
 
 
 

apps/docs/content/docs/platform/self-hosting/environment-variables.mdx

@@ -211,13 +211,16 @@ document rather than a rejected configuration. Common pairings:
 | `1536` | `text-embedding-3-small`, `text-embedding-3-large`, `gemini-embedding-001` |
 | `3072` | `text-embedding-3-large`, `gemini-embedding-001` |
 
-`sim-setup add knowledge-embeddings` walks through all of this — pick OpenAI, Azure OpenAI, Gemini,
-or Ollama and it writes the variables that family needs. `sim-setup status` then reports the one
-family your `KB_EMBEDDING_MODEL` actually selects, rather than every provider you happen to hold a
-key for.
-
-The Embeddings block reads the same `OLLAMA_URL`. It lists the embedding-capable models installed on
-that server with the width each one emits, so a workflow can embed locally without an API key.
+On a Compose install or source checkout, `sim-setup add knowledge-embeddings` walks through all of
+this — pick OpenAI, Azure OpenAI, Gemini, or Ollama and it writes the variables that family needs.
+`sim-setup config` then reports the one family your `KB_EMBEDDING_MODEL` actually selects, rather
+than every provider you happen to hold a key for. Helm releases set these values through your own
+chart values instead, and an Ollama server is yours to run either way — `sim-setup` configures Sim
+to reach one, never installs it.
+
+The Embeddings block reads the same `OLLAMA_URL`. It lists the models on that server that report an
+embedding capability, with the width each one emits where Ollama reports it, so a workflow can embed
+locally without an API key.
 
 ## Chat & PII
 

apps/docs/content/docs/platform/self-hosting/troubleshooting.mdx

@@ -252,7 +252,7 @@ The load balancer's backend timeout is closing them. On GKE, attach a `BackendCo
 
 Embeddings need a provider — set `OPENAI_API_KEY`, configure Azure OpenAI, set `KB_EMBEDDING_MODEL=gemini-embedding-001` with a Gemini key, or set `KB_EMBEDDING_MODEL=ollama/<model>` with `OLLAMA_URL` to embed on your own Ollama. If one is configured, verify pgvector is installed on the database.
 
-A document that fails with `vector 0 has N unexpected dimensions` means `EMBEDDING_OUTPUT_DIMS` does not match what the model actually emits. Sim cannot check this for you — the message names both widths, so set the variable to the one the model returned and recreate the knowledge base. Existing knowledge bases keep the width they were created with.
+A document that fails with `vector 0 has N unexpected dimensions` means `EMBEDDING_OUTPUT_DIMS` does not match what the model actually emits. The message names both widths. If the width the model returned is one of `384`, `768`, `1024`, `1536`, or `3072`, set the variable to it and recreate the knowledge base. If it is anything else, no column can store it — choose a model that emits one of those five instead, since setting an unstorable width silently falls back to `1536` and the next document fails the same way. Existing knowledge bases keep the width they were created with.
 
 ## Credentials Unreadable After a Restore
 

apps/sim/app/api/v1/knowledge/search/route.ts

@@ -192,11 +192,15 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
      * One query embedding serves every base in the request, so all of them must
      * be indexed the same way — including the vector width, which selects the
      * pgvector column each comparison reads.
+     *
+     * Built only for a query search. A tag-only request never embeds anything,
+     * so resolving a width it will not use would let one base recorded at an
+     * unstorable width fail a request that does not depend on it.
      */
-    const embeddingTargets = new Map<string, KbEmbeddingTarget>(
+    const embeddingTargets = new Map(
       accessibleKbs.map((kb) => [
         `${kb.embeddingModel}:${kb.embeddingDimension}`,
-        { model: kb.embeddingModel, dimensions: toKbEmbeddingDimensions(kb.embeddingDimension) },
+        { model: kb.embeddingModel, dimensions: kb.embeddingDimension },
       ])
     )
     if (hasQuery && embeddingTargets.size > 1) {
@@ -208,8 +212,19 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
         { status: 400 }
       )
     }
-    const queryEmbeddingTarget = [...embeddingTargets.values()][0]
-    const queryEmbeddingModel = queryEmbeddingTarget.model
+    const selectedTarget = [...embeddingTargets.values()][0]
+    const queryEmbeddingModel = selectedTarget.model
+    /**
+     * The width is narrowed to a storable one only for a query search, which is
+     * the only kind that reads a vector column. A tag-only search must not fail
+     * on a width it never uses.
+     */
+    const queryEmbeddingTarget: KbEmbeddingTarget | undefined = hasQuery
+      ? {
+          model: selectedTarget.model,
+          dimensions: toKbEmbeddingDimensions(selectedTarget.dimensions),
+        }
+      : undefined
 
     let results: SearchResult[]
     let queryEmbeddingIsBYOK: boolean | null = null
@@ -235,7 +250,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     } else if (hasQuery) {
       const queryEmbeddingResult = await generateSearchEmbedding(
         query!,
-        queryEmbeddingTarget,
+        queryEmbeddingTarget!,
         workspaceId
       )
       queryEmbeddingIsBYOK = queryEmbeddingResult.isBYOK
@@ -248,7 +263,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
         query,
         queryVector: {
           vector: JSON.stringify(queryEmbeddingResult.embedding),
-          dimensions: queryEmbeddingTarget.dimensions,
+          dimensions: queryEmbeddingTarget!.dimensions,
         },
         structuredFilters: hasFilters ? structuredFilters : undefined,
       })

apps/sim/blocks/blocks/embeddings.ts

@@ -157,7 +157,7 @@ export const EmbeddingsBlock: BlockConfig<EmbeddingsResponse> = {
   description: 'Generate embeddings',
   authMode: AuthMode.ApiKey,
   longDescription:
-    'Turn text into embedding vectors for semantic search, clustering, and similarity. Supports OpenAI, OpenRouter, Google Gemini, Cohere, and Mistral embedding models, plus any model on a self-hosted Ollama.',
+    'Turn text into embedding vectors for semantic search, clustering, and similarity. Supports OpenAI, OpenRouter, Google Gemini, Cohere, and Mistral embedding models, plus embedding models on a self-hosted Ollama.',
   category: 'tools',
   integrationType: IntegrationType.AI,
   docsLink: 'https://docs.sim.ai/integrations/embeddings',

apps/sim/lib/embeddings/catalog.ts

@@ -30,6 +30,13 @@ export const KB_EMBEDDING_STORAGE_DIMENSIONS = [3072, 1536, 1024, 768, 384] as c
 
 export type KbEmbeddingDimensions = (typeof KB_EMBEDDING_STORAGE_DIMENSIONS)[number]
 
+/**
+ * Widest width a knowledge base can be created at. Anything sized for "the
+ * largest response a base could produce" has to use this rather than the
+ * default, because the per-request item ceiling falls as the width grows.
+ */
+export const MAX_KB_EMBEDDING_DIMENSIONS: KbEmbeddingDimensions = KB_EMBEDDING_STORAGE_DIMENSIONS[0]
+
 /**
  * Width a knowledge base is created at when the deployment names no other one.
  * Matches the `embedding.embedding` column every base predating multi-width
@@ -286,7 +293,12 @@ export function getEmbeddingModelInfo(model: string): EmbeddingModelInfo {
 
 export function findEmbeddingModelInfo(model: string): EmbeddingModelInfo | undefined {
   if (isOllamaEmbeddingModel(model)) return buildOllamaEmbeddingModelInfo(model)
-  return EMBEDDING_MODELS[model]
+  /**
+   * Own-property lookup, not indexing: the record's prototype is
+   * `Object.prototype`, so `EMBEDDING_MODELS['toString']` would otherwise hand
+   * back an inherited function that every downstream field read then crashes on.
+   */
+  return Object.hasOwn(EMBEDDING_MODELS, model) ? EMBEDDING_MODELS[model] : undefined
 }
 
 export function getModelsForProvider(provider: KeyedEmbeddingProvider): string[] {

apps/sim/lib/embeddings/client.ts

@@ -972,13 +972,17 @@ export async function embedKnowledgeForDeployment(
   const capabilityValues = {
     ...env,
     /**
-     * The capability gates its providers on the family `KB_EMBEDDING_MODEL`
-     * names, but what matters here is the model this call actually embeds with:
-     * a knowledge base keeps the model it was created with, so one created
-     * before the deployment default changed must still resolve its own family's
-     * transports. Substituting it evaluates the chain for the model at hand.
+     * The capability gates its providers on the model and width
+     * `KB_EMBEDDING_MODEL` and `EMBEDDING_OUTPUT_DIMS` name, but what matters
+     * here is the target this call actually embeds with: a knowledge base keeps
+     * the model and width it was created with, so one created before the
+     * deployment default changed must still resolve its own family's transports.
+     * Both are substituted — the model alone would leave the deployment's width
+     * being validated against this base's family, which rejects the chain
+     * outright for a base whose family accepts a width the deployment's does not.
      */
     KB_EMBEDDING_MODEL: model,
+    EMBEDDING_OUTPUT_DIMS: String(dimensions),
     ...(workspaceKey ? { OPENAI_API_KEY: workspaceKey.apiKey } : {}),
   }
 

apps/sim/lib/embeddings/knowledge-embedding-family.test.ts

@@ -8,6 +8,7 @@ import {
   getEmbeddingModelInfo,
   getKbEligibleModels,
 } from '@/lib/embeddings/catalog'
+import { isKbEmbeddingModel } from '@/lib/knowledge/embedding-models'
 
 /**
  * `knowledgeEmbeddingFamily` decides which credential the setup CLI and the
@@ -28,16 +29,36 @@ describe('knowledgeEmbeddingFamily', () => {
   })
 
   it('classifies any model on the deployment’s own Ollama by its routing prefix', () => {
-    for (const model of ['ollama/nomic-embed-text', 'ollama/mxbai-embed-large:335m', 'OLLAMA/x']) {
+    for (const model of ['ollama/nomic-embed-text', 'ollama/mxbai-embed-large:335m']) {
       expect(knowledgeEmbeddingFamily({ KB_EMBEDDING_MODEL: model }), model).toBe('ollama')
     }
   })
 
-  it('falls back to the family of the model an unset variable defaults to', () => {
+  /**
+   * The classifier decides which credential the CLI reports as serving knowledge
+   * embeddings; the runtime decides which one actually gets used. An id the
+   * runtime rejects falls back to the default model, so the classifier has to
+   * call it that family too — otherwise a deployment holding only the credential
+   * it names passes its status check and fails every embedding call.
+   */
+  it('agrees with the runtime on ids the runtime does not accept', () => {
     const defaultFamily = getEmbeddingModelInfo(DEFAULT_EMBEDDING_MODEL).provider
+    const rejected = [
+      '',
+      '   ',
+      'not-a-model',
+      'gemini-embedding-999',
+      'Gemini-Embedding-001',
+      'gemini',
+      'OLLAMA/nomic-embed-text',
+      'ollama/',
+      'toString',
+      'constructor',
+    ]
+    for (const model of rejected) {
+      expect(isKbEmbeddingModel(model), `${model} must not be a KB model`).toBe(false)
+      expect(knowledgeEmbeddingFamily({ KB_EMBEDDING_MODEL: model }), model).toBe(defaultFamily)
+    }
     expect(knowledgeEmbeddingFamily({})).toBe(defaultFamily)
-    expect(knowledgeEmbeddingFamily({ KB_EMBEDDING_MODEL: '   ' })).toBe(defaultFamily)
-    /** An unrecognised id falls back to the default model, which is OpenAI's. */
-    expect(knowledgeEmbeddingFamily({ KB_EMBEDDING_MODEL: 'not-a-model' })).toBe(defaultFamily)
   })
 })

apps/sim/lib/embeddings/ollama-model-catalog.server.ts

@@ -36,6 +36,14 @@ export class OllamaEmbeddingModelNotFoundError extends Error {
   }
 }
 
+/** The configured server could not be reached at all — an outage, not a bad model id. */
+export class OllamaUnreachableError extends Error {
+  constructor(cause: string) {
+    super(`The configured Ollama server could not be reached: ${cause}`)
+    this.name = 'OllamaUnreachableError'
+  }
+}
+
 export class OllamaEmbeddingWidthUnknownError extends Error {
   constructor(model: string) {
     super(
@@ -88,12 +96,23 @@ function readEmbeddingLength(modelInfo: Record<string, unknown> | undefined): nu
 export async function fetchOllamaEmbeddingModelCatalog(
   signal?: AbortSignal
 ): Promise<OllamaEmbeddingModel[]> {
+  return (await loadOllamaEmbeddingModelCatalog(signal)).models
+}
+
+/**
+ * The catalog plus why it is empty, so a caller resolving one specific model can
+ * tell "not installed" apart from "no server answered". The selector only needs
+ * the list; the tool needs the distinction to pick a status code.
+ */
+async function loadOllamaEmbeddingModelCatalog(
+  signal?: AbortSignal
+): Promise<{ models: OllamaEmbeddingModel[]; unreachable?: string }> {
   /**
    * Hosted Sim runs no Ollama, and the loopback default cannot answer there, so
    * an unconfigured hosted deployment is not dialled at all. An explicit
    * `OLLAMA_URL` states an intent to reach a real server and is still honoured.
    */
-  if (isHosted && !isOllamaUrlConfigured()) return []
+  if (isHosted && !isOllamaUrlConfigured()) return { models: [] }
 
   let names: string[]
   try {
@@ -103,10 +122,9 @@ export async function fetchOllamaEmbeddingModelCatalog(
     names = tags.models.map((model) => model.name)
   } catch (error) {
     signal?.throwIfAborted()
-    logger.info('Ollama is not reachable; offering no embedding models', {
-      error: getErrorMessage(error, 'Unknown error'),
-    })
-    return []
+    const cause = getErrorMessage(error, 'Unknown error')
+    logger.info('Ollama is not reachable; offering no embedding models', { error: cause })
+    return { models: [], unreachable: cause }
   }
 
   const resolved = await mapWithConcurrency(names, OLLAMA_SHOW_CONCURRENCY, async (name) => {
@@ -132,7 +150,7 @@ export async function fetchOllamaEmbeddingModelCatalog(
     }
   })
 
-  return resolved.filter((model): model is OllamaEmbeddingModel => model !== null)
+  return { models: resolved.filter((model): model is OllamaEmbeddingModel => model !== null) }
 }
 
 /**
@@ -149,9 +167,11 @@ export async function getOllamaEmbeddingModelMetadata(
   signal?: AbortSignal
 ): Promise<Required<OllamaEmbeddingModel>> {
   const name = isOllamaEmbeddingModel(model) ? ollamaEmbeddingModelName(model) : model
-  const catalog = await fetchOllamaEmbeddingModelCatalog(signal)
+  const { models, unreachable } = await loadOllamaEmbeddingModelCatalog(signal)
+  /** An empty catalog because nothing answered is an outage, not a missing model. */
+  if (unreachable !== undefined) throw new OllamaUnreachableError(unreachable)
   /** Ollama resolves a bare name to its `:latest` tag, so both spellings match. */
-  const metadata = catalog.find(
+  const metadata = models.find(
     (candidate) => candidate.id === name || candidate.id === `${name}:latest`
   )
   if (!metadata) throw new OllamaEmbeddingModelNotFoundError(name)

apps/sim/lib/internal/embeddings/operations.ts

@@ -96,6 +96,11 @@ export async function executeEmbedding(
         .dimensions
     } catch (error) {
       context.signal?.throwIfAborted()
+      /**
+       * A model the caller can fix (not installed, or one whose width Ollama
+       * will not report) is a 400; anything else — an unreachable server above
+       * all — is an upstream failure and must not read as a bad request.
+       */
       const userError =
         error instanceof OllamaEmbeddingModelNotFoundError ||
         error instanceof OllamaEmbeddingWidthUnknownError