ruvnet/ruflo · error · Error

Router multimodal is enabled but LLM_ROUTER_MULTIMODAL_MODEL

Error message

Router multimodal is enabled but LLM_ROUTER_MULTIMODAL_MODEL is not correctly configured. Remove the image or configure a multimodal model via LLM_ROUTER_MULTIMODAL_MODEL.

What it means

Thrown by the router endpoint (endpoint.ts) when LLM_ROUTER_ENABLE_MULTIMODAL=true, the user submitted a message containing an image file, and getConfiguredMultimodalModelId(models) returned undefined. The router bypasses Arch-based routing for image inputs and routes directly to a configured multimodal model; if none is configured (or the configured id does not match any loaded model), it refuses to proceed rather than silently sending the image to a text-only model.

Source

Thrown at ruflo/src/ruvocal/src/lib/server/router/endpoint.ts:189

			yield {
				token: { id: 0, text: "", special: true, logprob: 0 },
				generated_text: null,
				details: null,
				routerMetadata: { route: selectedRoute, model: actualModel },
			};
			for await (const ev of gen) yield ev;
		}

		if (routerMultimodalEnabled && hasImageInput) {
			let multimodalCandidate: string | undefined;
			try {
				const all = await getModels();
				multimodalCandidate = getConfiguredMultimodalModelId(all);
			} catch (e) {
				logger.warn({ err: String(e) }, "[router] failed to load models for multimodal lookup");
			}
			if (!multimodalCandidate) {
				throw new Error(
					"Router multimodal is enabled but LLM_ROUTER_MULTIMODAL_MODEL is not correctly configured. Remove the image or configure a multimodal model via LLM_ROUTER_MULTIMODAL_MODEL."
				);
			}

			try {
				logger.info(
					{ route: ROUTER_MULTIMODAL_ROUTE, model: multimodalCandidate },
					"[router] multimodal input detected; bypassing Arch selection"
				);
				const ep = await createCandidateEndpoint(multimodalCandidate);
				const gen = await ep({ ...params });
				return metadataThenStream(gen, multimodalCandidate, ROUTER_MULTIMODAL_ROUTE);
			} catch (e) {
				const { message, statusCode } = extractUpstreamError(e);
				logger.error(
					{
						route: ROUTER_MULTIMODAL_ROUTE,
						model: multimodalCandidate,

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Set LLM_ROUTER_MULTIMODAL_MODEL to the id of a model that is present in the loaded models list and actually supports image input.
2. Verify the id matches an entry returned by /models (check the model registry / logs).
3. If you do not have a multimodal backend, disable LLM_ROUTER_ENABLE_MULTIMODAL or instruct users not to attach images.
4. Ensure the multimodal model's multimodal flag and multimodalAcceptedMimetypes include image/*.

Example fix

# before
LLM_ROUTER_ENABLE_MULTIMODAL=true
# LLM_ROUTER_MULTIMODAL_MODEL unset

# after
LLM_ROUTER_ENABLE_MULTIMODAL=true
LLM_ROUTER_MULTIMODAL_MODEL=meta-llama/Llama-4-Scout-17B-16E-Instruct

function isMultimodalConfigured(models: ProcessedModel[]): boolean {
  const id = (config.LLM_ROUTER_MULTIMODAL_MODEL || "").trim();
  if (!id) return false;
  const m = models.find((x) => x.id === id || x.name === id);
  return Boolean(m && m.multimodal);
}

if (routerMultimodalEnabled && !isMultimodalConfigured(models)) {
  logger.warn("Disable LLM_ROUTER_ENABLE_MULTIMODAL or set a valid LLM_ROUTER_MULTIMODAL_MODEL");
}

function isImageMessage(message: { files?: { mime?: string }[] }): boolean {
  return Boolean((message.files ?? []).some((f) => typeof f?.mime === "string" && f.mime.startsWith("image/")));
}

try { const gen = await routerEndpoint(params); }
catch (e) {
  if (e instanceof Error && /LLM_ROUTER_MULTIMODAL_MODEL is not correctly configured/.test(e.message)) {
    return { error: "multimodal-not-configured", retryableAfterConfig: true };
  }
  throw e;
}

When it happens

Trigger: User uploads an image in a conversation using the router alias model while LLM_ROUTER_ENABLE_MULTIMODAL is true but LLM_ROUTER_MULTIMODAL_MODEL is unset, references a non-existent model id, or points at a model that was not returned by the upstream /models list (so getConfiguredMultimodalModelId cannot match it).

Common situations: Operators flipping LLM_ROUTER_ENABLE_MULTIMODAL=true without also setting LLM_ROUTER_MULTIMODAL_MODEL; typo in the model id; the configured multimodal model was renamed/retired upstream; the upstream registry was filtered (MODELS overrides) and excluded the multimodal model; a stale env var from a previous deployment.

Related errors

• OPENAI_BASE_URL not set
• Routes config must be a flat array of routes
• Invalid route entry: ${JSON.stringify(r)}
• Duplicate route name: ${r.name}
• ${ENV_ENABLE_FLAG} is set but ${ENV_KEY_VAR} is not. Provide

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/321276439118be6b. Report an issue: GitHub.