What causes "OPENAI_BASE_URL not set" in ruvnet/ruflo?

Set OPENAI_BASE_URL to an OpenAI-compatible base, e.g. https://router.huggingface.co/v1.

ruvnet/ruflo · critical · Error

OPENAI_BASE_URL not set

Error message

OPENAI_BASE_URL not set

What it means

Thrown by buildModels at startup when config.OPENAI_BASE_URL is unset. This build of chat-ui is OpenAI-compatible-only and bootstraps its entire model registry by fetching ${OPENAI_BASE_URL}/models; without that base URL there is no source of models and the app cannot start. The check happens before any network I/O.

Source

Thrown at ruflo/src/ruvocal/src/lib/server/models.ts:302

		{
			total: summary.total,
			added: summary.added,
			removed: summary.removed,
			changed: summary.changed,
			durationMs: summary.durationMs,
		},
		"[models] Model cache refreshed"
	);

	return summary;
};

const buildModels = async (): Promise<ProcessedModel[]> => {
	if (!openaiBaseUrl) {
		logger.error(
			"OPENAI_BASE_URL is required. Set it to an OpenAI-compatible base (e.g., https://router.huggingface.co/v1)."
		);
		throw new Error("OPENAI_BASE_URL not set");
	}

	try {
		const baseURL = openaiBaseUrl;
		logger.info({ baseURL }, "[models] Using OpenAI-compatible base URL");

		// Canonical auth token is OPENAI_API_KEY; keep HF_TOKEN as legacy alias
		const authToken = config.OPENAI_API_KEY || config.HF_TOKEN;

		// Use auth token from the start if available to avoid rate limiting issues
		// Some APIs rate-limit unauthenticated requests more aggressively
		const response = await fetch(`${baseURL}/models`, {
			headers: authToken ? { Authorization: `Bearer ${authToken}` } : undefined,
		});
		logger.info({ status: response.status }, "[models] First fetch status");
		if (!response.ok && response.status === 401 && !authToken) {
			// If we get 401 and didn't have a token, there's nothing we can do
			throw new Error(

View on GitHub (pinned to 6b01dc5a68)

Solutions

Set OPENAI_BASE_URL to an OpenAI-compatible base, e.g. https://router.huggingface.co/v1.
For local dev, copy .env to .env.local and fill in the value.
For docker/k8s, inject OPENAI_BASE_URL via -e / envFrom.
Double-check spelling: it is OPENAI_BASE_URL, not OPENAI_API_BASE_URL or OPENAI_BASE.

Example fix

# before (.env.local)
# OPENAI_BASE_URL=

# after
OPENAI_BASE_URL=https://router.huggingface.co/v1
OPENAI_API_KEY=hf_xxx

Defensive patterns

Strategy: validation

Validate before calling

function requireOpenAiBaseUrl(): string {
  const url = config.OPENAI_BASE_URL?.trim();
  if (!url) throw new Error("OPENAI_BASE_URL not set");
  return url.replace(/\/$/, "");
}

Type guard

function isOpenAiBaseUrlSet(value: unknown): value is string {
  return typeof value === "string" && value.trim().length > 0;
}

Try / catch

// startup guard; cannot recover at runtime without env
if (!process.env.OPENAI_BASE_URL) {
  console.error("Set OPENAI_BASE_URL to an OpenAI-compatible base.");
  process.exit(1);
}

Prevention

Add OPENAI_BASE_URL to a required-env check that runs before importing the server.
Ship a .env.example with OPENAI_BASE_URL populated for common gateways.
In containers, validate required env in an entrypoint script before exec'ing the app.

When it happens

Trigger: Module load of $lib/server/models.ts when OPENAI_BASE_URL is missing or empty. Because models.ts calls rebuildModels() at the top level (await rebuildModels() at line 494), this throws during server startup/import, failing the SvelteKit boot.

Common situations: Fresh deploy that did not populate env; .env.local missing or not loaded; CI/test run without env injection; docker container started without -e OPENAI_BASE_URL; env var name typo (e.g. OPENAI_API_BASE_URL).

Related errors

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