Troubleshooting

This page covers the most common issues you may encounter when using WinCatalog AI Bridge.

## Status Indicator Colors

The colored dot in the top-right corner of the AI Bridge window indicates the current connection status. Click it at any time to open **Settings**.

Green: Provider is installed and running, model is ready, you're good to go.

Yellow: Provider is installed but has an issue (e.g., server not running, model not loaded). Click the dot to open Settings; use Start Server** or load the model.

Red: Provider is not reachable or not installed. Check the provider application, verify the IP/port, or install the provider.

The same status information appears as a banner message at the top of the window with more detail.

Common Issues

"Health check failed. Click to open settings."

The AI Bridge cannot reach the provider server.

Possible causes and fixes:

1. Provider not running — Open LM Studio or Ollama and start the server. In AI Bridge Settings, the System Status section shows "{provider} is installed but not running". Click Start Server to start it automatically.

2. Wrong port — Check that the Port in Provider Configuration matches the port the provider is actually using (default: 1234 for LM Studio, 11434 for Ollama).

3. Wrong IP address — If you're running the provider on the same machine, IP Address should be localhost. If it's on another machine, verify the IP address.

4. Firewall blocking the connection — Check Windows Firewall or any security software that might be blocking local connections on the provider's port.

"{provider} is running but model '{model}' is not loaded."

The AI server is running, but the selected model is not available.

Fix: In AI Bridge Settings → Model Configuration, click Refresh List to refresh the list, then select an available model. If no models appear, you need to download one:

In LM Studio: download the model through the LM Studio interface as described in Getting started
In Ollama: run `ollama pull <model-name>` in a terminal, or use Download Selected Model in AI Bridge Settings

"No vision-capable models are available."

None of the models available in your provider can analyze images.

Fix: Download a vision-capable model. Recommended options:

LM Studio: google/gemma-4-e2b
Ollama: qwen3.5:4b (run `ollama pull qwen3.5:4b`)

Items remain in the queue with "Failed" status

An item failed to process. This can happen when:

The model returned an empty response
The image thumbnail could not be read
The connection to the provider was lost during processing

Fix: Select the failed items and click Process Selection to retry. If failures persist, check the log files for details (see below).

Processing is very slow

Processing speed depends on your hardware (CPU/GPU) and the size of the AI model.

Tips:

Use a smaller model (e.g., 4B parameter models are much faster than 13B+ models)
Reduce the context size to 4096 in LM Studio model settings
Enable GPU acceleration in LM Studio or Ollama if your GPU supports it
Close other resource-intensive applications during processing
Stop the process, restart LM Studio or Ollama, and continue

AI descriptions are in the wrong language

The AI model is generating descriptions in a language you didn't expect.

Fix: Open AI Bridge Settings → Advanced Settings → Output Language (scroll the window to bottom if you don't see this option) and select the correct language. If your language is not in the list, select Other and type the language name. Then re-process the affected items.

AI descriptions are low quality or inaccurate

The model may produce vague or incorrect descriptions for some images.

Tips:

Try a larger model (e.g., 8B instead of 4B) — larger models are generally more accurate
Ensure the image thumbnails in WinCatalog are of reasonable quality and size — very small thumbnails give the model less information to work with
Some image types (screenshots, documents, abstract art) are harder for AI to describe accurately

Keep in mind that AI descriptions are meant to help with search and catalog organization — they are not guaranteed to be accurate. Do not rely on them in situations where precision matters, such as medical, legal, or financial content, or images with culturally sensitive symbols. See the disclaimer in the overview for details.

Processing stops with a timeout error

The connection to the AI provider was lost or the model is taking too long to respond.

Possible causes and fixes:

Model is too large for your hardware — Processing a single image should not take more than 30–60 seconds. If it does, switch to a smaller model.
Provider crashed — Check if LM Studio or Ollama is still running. Restart it if needed, then retry the failed items.
System went to sleep — If your computer entered sleep mode during processing, the connection may have been lost. Wake the computer and retry.

Items added from WinCatalog don't appear in AI Bridge

WinCatalog launches AI Bridge automatically when you use Descrobe images using AI (context menu) or Open Queue on the Ribbon Toolbar on the AI Tools tab. If AI Bridge is already open but items don't appear in the queue:

Switch to the AI Queue tab in AI Bridge — items may already be there
Restart AI Bridge from WinCatalog to ensure it connects to the right catalog
Restart WinCatalog and try again

Finding Log Files

AI Bridge writes detailed log files that can help diagnose problems. By default, logs are stored in the Windows AppData folder.

To locate the log files:

Open File Explorer
Navigate to: %AppData%\WinCatalog (hint: %AppData% is a special shortcut for a system folder in Windows)

Each day's log is a separate file named by date (e.g., AiBridge-20260415.log). Logs rotate automatically and are kept for 7 days.

If you need to report an issue, include the relevant log file along with a description of the problem.

Settings Location

AI Bridge stores its settings in the Windows Registry under:

HKEY_CURRENT_USER\SOFTWARE\OrangeCat Software\WinCatalog

To reset all AI Bridge settings to defaults, delete the AI Bridge-related keys from this registry path using the Windows Registry Editor (regedit). This does not affect your catalog data or AI descriptions.

Still Having Issues?

If none of the above steps resolve your problem:

Verify that the provider (LM Studio or Ollama) works correctly outside of AI Bridge
Try Test Connection in AI Bridge Settings to get a specific error message
Check the log files for error details
Reinstall the AI provider if the installation appears corrupted

In addition to above, check the Frequently Asked Questions section