Troubleshooting Ollama Connection Issues in Prompt-Optimizer: A Complete Guide

To fix Ollama connection failures in prompt-optimizer, verify the service is running on http://localhost:11434, set OLLAMA_ORIGINS=* for CORS in web builds, configure VITE_CUSTOM_API_BASE_URL to match your endpoint, and use the desktop or Docker builds to bypass HTTPS mixed-content restrictions.

Prompt-optimizer provides a local Ollama adapter that communicates through the OpenAI-compatible HTTP API, but browser-based deployments face unique networking constraints. Whether you are running the web UI, desktop Electron client, or a Docker container, understanding how the adapter in packages/core/src/services/llm/adapters/ollama-adapter.ts expects to connect will help you resolve failures quickly.

Verify Ollama Service Status

Before adjusting prompt-optimizer settings, confirm that Ollama is actually reachable on your machine. The adapter defaults to http://localhost:11434/v1, so the service must be listening on that port.

1. Start the Ollama server with ollama serve (default port 11434).
2. Check health by running curl http://localhost:11434/api/version — you should receive a JSON response containing the version number.
3. Verify model availability with ollama list to ensure your target model (e.g., qwen3:8b) is installed.

If these commands fail, the issue is at the Ollama level, not within prompt-optimizer.

Configure CORS for Web Deployments

Browser security prevents web pages from calling http://localhost unless the server explicitly allows the origin. The prompt-optimizer README documents the required environment variable for Ollama:

Set OLLAMA_ORIGINS=* to permit requests from any origin.

Apply this in your shell before starting Ollama:

export OLLAMA_ORIGINS=*
ollama serve

Or pass it when running Ollama via Docker. Without this setting, the browser will block the connection with a CORS error before prompt-optimizer can communicate with the adapter.

Set the Correct Base URL and API Key

The OllamaAdapter class defines a default endpoint that the UI falls back to when no custom URL is provided:

const OLLAMA_DEFAULT_BASE_URL = 'http://localhost:11434/v1';

If you run Ollama on a different host or port, override this via environment variables in your .env.local file:

VITE_CUSTOM_API_BASE_URL=http://localhost:11434/v1
VITE_CUSTOM_API_KEY=ollama
VITE_CUSTOM_API_MODEL=qwen3:8b

The adapter's connectionSchema marks both baseURL and apiKey as optional, but the underlying OpenAI SDK requires a non-empty key. The adapter handles this by injecting a fallback value when the field is missing:

const OLLAMA_FALLBACK_API_KEY = 'ollama';
const apiKey = rawApiKey.trim() ? rawApiKey : OLLAMA_FALLBACK_API_KEY;

This ensures the connection succeeds even when you leave the API key field blank in the UI.

Resolve Mixed Content Errors

When prompt-optimizer is served over HTTPS (such as the Vercel demo or online versions), browsers block insecure http:// calls to Ollama due to mixed-content policies. The README explicitly warns about this limitation.

Solutions:

• Use the Desktop Application: The Electron build performs native HTTP requests without browser restrictions, making it the most reliable method for local Ollama connections.
• Deploy via Docker: Running prompt-optimizer in Docker exposes it over HTTP (http://localhost:8081), matching Ollama's protocol and avoiding mixed-content blocks.
• Configure a Reverse Proxy: If you must use the web version, place a TLS-terminating proxy (like Nginx) in front of Ollama to expose https://localhost:8443, then set VITE_CUSTOM_API_BASE_URL to that HTTPS endpoint.

Verify Provider Registration

The adapter must be registered before the UI can display it as an option. In packages/core/src/services/llm/adapters/registry.ts, the system instantiates the adapter:

import { OllamaAdapter } from './ollama-adapter';
const ollamaAdapter = new OllamaAdapter();

When you select "Local Ollama" in the interface, the provider metadata (id: 'ollama', corsRestricted: false, requiresApiKey: false) is returned by the registry. If Ollama does not appear in the dropdown, ensure your environment variables are loaded (Vite automatically injects variables prefixed with VITE_) and refresh the provider list.

Debug with Logging and Test Scripts

Both the desktop and web builds emit console logs when requests fail. Open the browser DevTools or the Electron developer console and look for error messages such as:

[OllamaImageAdapter] Failed to fetch models: ...

You can also verify connectivity programmatically using the library's public API:

import { createModelManager } from '@prompt-optimizer/core';
import { OllamaAdapter } from '@prompt-optimizer/core/services/llm/adapters/ollama-adapter';

async function testOllama() {
  const manager = createModelManager({
    provider: new OllamaAdapter(),
    connection: { baseURL: 'http://localhost:11434/v1' }
  });
  
  const models = await manager.getModels();
  console.log('Available Ollama models:', models);
}

testOllama().catch(console.error);

If the array is empty, Ollama is reachable but has no models installed; run ollama pull <model> and retry.

Summary

• Confirm Ollama is running on localhost:11434 and responds to health checks before troubleshooting prompt-optimizer.
• Set OLLAMA_ORIGINS=* when using web builds to prevent CORS errors.
• Configure VITE_CUSTOM_API_BASE_URL and VITE_CUSTOM_API_MODEL in your environment to override the default http://localhost:11434/v1 endpoint.
• Use the desktop or Docker builds to bypass HTTPS mixed-content restrictions that block browser-based connections to local Ollama instances.
• Check the registry in packages/core/src/services/llm/adapters/registry.ts to ensure the Ollama provider is properly instantiated.

Frequently Asked Questions

Why does the online version of prompt-optimizer fail to connect to my local Ollama even with CORS enabled?

This occurs because browsers enforce mixed-content policies that block HTTPS pages from making HTTP requests to localhost. Even with OLLAMA_ORIGINS=* set, the protocol mismatch prevents the connection. Use the desktop application or Docker deployment instead, as these run over HTTP and bypass browser security restrictions.

What is the default base URL for the Ollama adapter, and how do I change it?

The adapter defaults to http://localhost:11434/v1 as defined in packages/core/src/services/llm/adapters/ollama-adapter.ts. To override this, set the VITE_CUSTOM_API_BASE_URL environment variable in your .env.local file or shell environment before starting the application.

Does Ollama require an API key when used with prompt-optimizer?

No, Ollama does not require a real API key. However, the underlying OpenAI SDK used by the adapter requires a non-empty string. The OllamaAdapter automatically injects a fallback value of "ollama" when the key is missing, so you can leave the API key field blank or set VITE_CUSTOM_API_KEY=ollama in your configuration.

How can I verify that prompt-optimizer can reach my Ollama instance programmatically?

You can use the library's public API to test connectivity. Import createModelManager and OllamaAdapter, instantiate the manager with your base URL, and call getModels(). If Ollama is reachable, this returns an array of available models; if empty, Ollama is running but has no models installed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}