fix(embeddings): one rule for a configured Ollama server, and stop forcing its width

Fourth round of review findings:

- Make the setup wizard's EMBEDDING_OUTPUT_DIMS optional and undefaulted for
  Ollama; requiring it suppressed the server-side width detection entirely, and
  its 768 default was wrong for a 384-wide model
- Replace three different notions of 'an Ollama server is configured' with one
  predicate shared by the selector, the width lookup, and the embedding client:
  self-hosted is served by the loopback default as the chat provider already is,
  and only hosted must be pointed at a server
- Document that an ollama/ model id is taken at face value rather than falling
  back, so a model absent from the server fails creation

Author: icecrasher321

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

@@ -190,7 +190,7 @@ See [Observability](/platform/self-hosting/observability).
 
 | Variable | Description |
 |----------|-------------|
-| `KB_EMBEDDING_MODEL` | Embedding model for new knowledge bases. Defaults to `text-embedding-3-small`; use `ollama/<model>` for a model on your own Ollama. An unsupported value falls back to the default |
+| `KB_EMBEDDING_MODEL` | Embedding model for new knowledge bases. Defaults to `text-embedding-3-small`; use `ollama/<model>` for a model on your own Ollama. An unrecognised hosted model id falls back to the default, but an `ollama/` id is taken at face value — if that model is not on the server, knowledge-base creation fails rather than falling back |
 | `EMBEDDING_OUTPUT_DIMS` | Vector width new knowledge bases are stored at: `384`, `768`, `1024`, `1536` (default), or `3072`. It must be a width the chosen model can emit; anything else falls back to `1536` with a warning |
 | `OPENROUTER_API_KEY` | Fallback route for the OpenAI embedding models — used when it is set and `OPENAI_API_KEY` is not the chosen path |
 | `COHERE_API_KEY` | Enables the Knowledge block reranker |

apps/sim/lib/embeddings/client.test.ts

@@ -1431,11 +1431,24 @@ describe('ollama embeddings', () => {
     ).rejects.toThrow('has 1024 unexpected dimensions; expected 768')
   })
 
-  it('refuses to fall back to the loopback default when OLLAMA_URL names no server', async () => {
-    await expect(
-      embed(['hello'], { model: 'ollama/nomic-embed-text', dimensions: 768, projectInputs: null })
-    ).rejects.toThrow('OLLAMA_URL must be configured for Ollama embeddings')
-    expect(fetchMock).not.toHaveBeenCalled()
+  /**
+   * A self-hosted deployment runs alongside its own Ollama, so the loopback
+   * default is a working configuration that needs no env var — the same rule
+   * the chat provider and the block's model selector apply. Requiring the
+   * variable here would make embedding stricter than the list that offers the
+   * models.
+   */
+  it('serves a self-hosted deployment from the loopback default', async () => {
+    fetchMock.mockResolvedValue(jsonResponse(ollamaBody([[1, 2, 3]], 768)))
+
+    const result = await embed(['hello'], {
+      model: 'ollama/nomic-embed-text',
+      dimensions: 768,
+      projectInputs: null,
+    })
+
+    expect(fetchMock.mock.calls[0][0]).toBe('http://localhost:11434/api/embed')
+    expect(result.dimensions).toBe(768)
   })
 
   it('ignores a caller-supplied key rather than sending one Ollama cannot use', async () => {

apps/sim/lib/embeddings/client.ts

@@ -15,7 +15,7 @@ import {
   readResponseJsonWithLimit,
   readResponseTextWithLimit,
 } from '@/lib/core/utils/stream-limits'
-import { getOllamaUrl, isOllamaUrlConfigured } from '@/lib/core/utils/urls'
+import { getOllamaUrl } from '@/lib/core/utils/urls'
 import {
   DEFAULT_EMBEDDING_MODEL,
   type EmbeddingModelInfo,
@@ -25,6 +25,7 @@ import {
   resolveDimensions,
 } from '@/lib/embeddings/catalog'
 import { resolveProviderKey } from '@/lib/embeddings/keys'
+import { isOllamaServerConfigured } from '@/lib/embeddings/ollama-model-catalog.server'
 import { DEFAULT_OPENROUTER_EMBEDDING_MODEL } from '@/lib/embeddings/openrouter-models'
 import { getAdapterFactory } from '@/lib/embeddings/providers'
 import {
@@ -364,13 +365,15 @@ async function resolveProvider(model: string, options: EmbedOptions): Promise<Re
   /**
    * Ollama runs on the deployment's own server and takes no credential, so it
    * resolves before every key-bearing path and ignores a caller-supplied key
-   * rather than pretending one applies. `OLLAMA_URL` must name a server: the
-   * loopback default `getOllamaUrl` falls back to is a development convenience,
-   * and silently indexing a knowledge base against a localhost that answers
-   * nothing is worse than saying so.
+   * rather than pretending one applies.
+   *
+   * A self-hosted deployment may leave `OLLAMA_URL` unset and be served by the
+   * loopback default, exactly as the chat provider is; only hosted Sim, which
+   * runs no Ollama, has to be pointed at one. Requiring the variable everywhere
+   * would have made this stricter than the selector that offers the models.
    */
   if (info.provider === 'ollama') {
-    if (!isOllamaUrlConfigured()) {
+    if (!isOllamaServerConfigured()) {
       throw new Error('OLLAMA_URL must be configured for Ollama embeddings')
     }
     const baseUrl = getOllamaUrl().replace(/\/+$/, '')

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

@@ -27,6 +27,22 @@ export interface OllamaEmbeddingModel {
   dimensions?: number
 }
 
+/**
+ * Whether this deployment has an Ollama server to talk to.
+ *
+ * Self-hosted deployments run alongside their own Ollama, so the loopback
+ * default `getOllamaUrl` falls back to is a working configuration that needs no
+ * env var — the same rule the chat provider's model route applies. Hosted Sim
+ * runs none, so there the address must be stated or there is nothing to reach.
+ *
+ * Exported because the selector, this module's width lookup, and the embedding
+ * client all have to answer it identically: a selector that lists models the
+ * client then refuses to embed with is worse than either behaviour alone.
+ */
+export function isOllamaServerConfigured(): boolean {
+  return !isHosted || isOllamaUrlConfigured()
+}
+
 export class OllamaEmbeddingModelNotFoundError extends Error {
   constructor(model: string) {
     super(
@@ -109,12 +125,8 @@ export async function fetchOllamaEmbeddingModelCatalog(
 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 { models: [] }
+  /** Nothing to dial: an unconfigured hosted deployment has no server to reach. */
+  if (!isOllamaServerConfigured()) return { models: [] }
 
   let names: string[]
   try {
@@ -177,13 +189,8 @@ export async function getOllamaEmbeddingModelMetadata(
 ): Promise<Required<OllamaEmbeddingModel>> {
   const name = isOllamaEmbeddingModel(model) ? ollamaEmbeddingModelName(model) : model
   if (!name) throw new OllamaEmbeddingModelNotFoundError(model)
-  /**
-   * The same requirement `resolveProvider` enforces before embedding. Without it
-   * a developer machine with an unset `OLLAMA_URL` and a local server answering
-   * on the loopback default would resolve a width here and create a knowledge
-   * base that every later embedding call refuses to serve.
-   */
-  if (!isOllamaUrlConfigured()) {
+  /** The same rule the selector and the embedding client apply. */
+  if (!isOllamaServerConfigured()) {
     throw new OllamaUnreachableError('OLLAMA_URL is not configured')
   }
 

packages/sim-setup/src/capability-config.ts

@@ -952,16 +952,16 @@ export const KNOWLEDGE_EMBEDDINGS_SETUP = defineCapabilitySetup(KNOWLEDGE_EMBEDD
         },
         {
           /**
-           * Asked rather than derived: Sim cannot know what a local model emits
-           * until it is running, and a width that does not match is the one
-           * misconfiguration this path cannot detect for the operator.
+           * Optional and undefaulted on purpose. Sim reads the width from the
+           * server when this is unset, which is more reliable than any answer
+           * the operator can give here — and a default of 768 would be wrong
+           * for a 384-wide model such as `all-minilm` while also suppressing
+           * the lookup that would have got it right.
            */
           type: 'field',
           key: 'EMBEDDING_OUTPUT_DIMS',
           input: 'text',
-          required: true,
-          defaultValue: '768',
-          hint: 'must equal what the model emits: 384, 768, 1024, 1536, or 3072',
+          hint: 'optional — leave blank and Sim reads the width from your Ollama server',
           validate: true,
         },
       ],