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

> Troubleshoot Ollama connection issues in prompt-optimizer. Learn to verify the Ollama service, configure CORS, set custom API URLs, and use desktop or Docker builds for smooth integration.

- Repository: [且炼时光/prompt-optimizer](https://github.com/linshenkx/prompt-optimizer)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/linshenkx/prompt-optimizer/blob/main/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:

```bash
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:

```ts
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:

```dotenv
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:

```ts
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`](https://github.com/linshenkx/prompt-optimizer/blob/main/packages/core/src/services/llm/adapters/registry.ts), the system instantiates the adapter:

```ts
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:

```typescript
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`](https://github.com/linshenkx/prompt-optimizer/blob/main/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`](https://github.com/linshenkx/prompt-optimizer/blob/main/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.