Skip to main content

Appendix C — Troubleshooting

Installation & startup​

Docker not starting​

Symptom: The launcher reports "Docker daemon is not running."

Fix:

  1. Open Docker Desktop from the Start Menu.
  2. Wait for the whale icon in the system tray to stop animating (up to 60 seconds on a cold start).
  3. Double-click the Conio launcher shortcut again.

If Docker Desktop is not installed, see Installation — Step 1 for the correct installer for your machine architecture.

Docker hangs on startup / WSL errors​

Symptom: Docker Desktop opens but the progress bar freezes, the whale icon spins indefinitely, or you see a message such as "WSL 2 installation is incomplete" or "WSL kernel update required."

Docker Desktop requires Windows Subsystem for Linux 2 (WSL 2) and hardware virtualisation. One or more of these may not be enabled.

Fix — enable required Windows features:

  1. Press Win + R, type optionalfeatures, and press Enter.
  2. Check both:
    • Virtual Machine Platform
    • Windows Subsystem for Linux
  3. Click OK and restart your machine.
  4. After restart, open PowerShell and run: 
    wsl --update
  5. Launch Docker Desktop again.

Fix — enable hardware virtualisation (if Docker still hangs):

Virtualisation must be enabled in your machine's firmware (BIOS/UEFI):

  1. Go to Settings → System → Recovery → Advanced startup → Restart now.
  2. Navigate to Troubleshoot → Advanced options → UEFI Firmware Settings → Restart.
  3. In the BIOS/UEFI menu, find the CPU settings and enable Intel Virtualization Technology (VT-x) or AMD-V / SVM, depending on your processor.
  4. Save and exit. Windows will restart.
  5. Open Docker Desktop — the startup hang should be resolved.
Most common fix

In practice, simply enabling Virtual Machine Platform in Windows Features and restarting resolves the Docker startup hang in the majority of cases. Try that first before going into BIOS settings.

WSL2 error: "Virtual Machine Platform not enabled" / hypervisor not installed​

Symptom: Docker hangs at startup. Running wsl in a terminal produces:

WSL2 is not supported with your current machine configuration.
Please enable the "Virtual Machine Platform" optional component and ensure
virtualization is enabled in the BIOS.
Enable "Virtual Machine Platform" by running: wsl.exe --install --no-distribution
Error code: Wsl/Service/CreateInstance/CreateVm/HCS/HCS_E_HYPERV_NOT_INSTALLED

This means the Windows hypervisor is not set to launch automatically at boot — a common state after certain Windows updates, BIOS changes, or if another virtualisation tool previously disabled it.

Fix:

  1. Open PowerShell as Administrator (right-click PowerShell → Run as administrator) and run: 
    bcdedit /set hypervisorlaunchtype auto
  2. Shut down the computer completely. Do not use Restart — a cold power-off is required for the firmware to reinitialise the hypervisor correctly.
  3. Power the machine back on. Open a terminal and run: 
    wsl
    You should see a WSL prompt or a message showing the current distribution. If the error is gone, WSL is working.
  4. Close the terminal and launch Docker Desktop. It should start normally.
Why shutdown instead of restart?

A Windows Restart performs a "fast restart" that keeps the kernel session partially warm. A full Shutdown → Power On forces the firmware to reinitialise the hypervisor from scratch, which is required for the bcdedit change to take effect.

Mandatory update overlay blocking the app​

Symptom: A full-screen overlay appears saying a mandatory update is required. The app is unusable.

Fix: Pull the latest image and restart:

docker pull quanomics/conio:latest

Then stop and relaunch using the shortcuts. The overlay will not appear once the image is up to date.

In-app update not working / update banner persists after updating​

Symptom: You clicked Update Now in the app banner but after the page reloads the banner is still visible, or the version shown in Settings has not changed.

This usually means either the Docker image download is still in progress, or the automatic update did not trigger correctly.

Manual update procedure:

  1. Open a PowerShell window in your Conio installation folder (the folder that contains docker-compose.yml).
  2. Run: 
    docker compose pull
    docker compose up -d --force-recreate
  3. Wait approximately 30 seconds for the new container to start, then reload http://localhost:8000 in your browser.

docker compose pull downloads the latest image from Docker Hub. --force-recreate ensures Docker replaces the running container with the new image rather than reusing the existing one.

Finding your installation folder

The default installation path is C:\Conio\. If you chose a custom location, right-click the Conio desktop shortcut → Properties → Start in — that directory is your installation folder.

If the banner still appears after a successful pull, the new image may not yet be available on Docker Hub. Wait a few minutes and repeat the steps above.

App loads but shows FREE badge when a Pro token is set​

Symptom: You added LICENSE_TOKEN to docker-compose.yml but the sidebar still shows FREE.

Checklist:

  1. Confirm the token is on the LICENSE_TOKEN= line with no extra spaces or quotes around the value.
  2. Confirm you stopped and restarted the container after editing the file (Stop Conio → Conio).
  3. Check Settings → License for any error message (e.g. "Token not found" or "Token inactive").
  4. Verify your internet connection — the first validation requires a network call to the license server.

AI features​

AI Refine error panel persists after retrying​

Symptom: Red error panel on a table card does not clear even after another Refine run.

Error messages and fixes:

Error messageCauseFix
Resource exhausted / Quota exceededProvider rate limit hitWait for the quota window to reset (usually 60 seconds for Gemini). The error panel shows the retry time when available.
API key not validWrong or revoked keyGenerate a new API key in your provider's console; update in Settings → AI Model.
TimeoutSlow network or large batchRefine will retry unprocessed batches on the next run. If persistent, check network latency to the provider.
Malformed AI responseProvider returned non-JSON outputTemporary provider issue; retry. If using Claude, ensure you are on an up-to-date version of Conio (fence-stripping is handled automatically).

A clean Refine run (all batches succeed) automatically dismisses the error panel.

Match All returns no matches (all items stay pending)​

Checklist:

  1. Confirm the BOQ table has been through AI Refine. Un-refined items score poorly against most rate tables.
  2. Check the Matcher Scoring Profile — if all three weights are zero or the profile is in an invalid state, no scoring occurs.
  3. Verify the candidate threshold in Settings is not set too high. Lower it to see if candidates begin appearing.
  4. Use the Test Sandbox on a specific item to confirm whether any candidates score above zero. If they do, the issue is the threshold; if not, the descriptions may be too dissimilar to match.

Batch URA generates Cold every time (no template applied)​

Symptom: Every URA banner shows no template reference; "Cold" generation for all items.

Cause: Templates exist in the library but their keywords are too specific (raw BOQ phrases instead of generic trade terms).

Fix:

  1. Open Settings → Recipe Library.
  2. For each template, click the edit icon and replace the Keywords field with generic, trade-level terms. See Template Library — Writing good keywords.
  3. Re-run Batch URA. The improved keywords will now score above the match floor.

Ollama — "Cannot connect" or "Name or service not known"​

Ollama connection errors fall into three categories. Use the error message to identify which applies.

Failed to resolve 'host.docker.internal' — Name resolution error​

The Docker container cannot find your Windows host by hostname. This means the extra_hosts entry is missing from your docker-compose.yml.

Fix: Open your docker-compose.yml (in the Conio installation folder) and add the extra_hosts block:

services:
  app:
    image: quanomics/conio:latest
    ...
    extra_hosts:
      - "host.docker.internal:host-gateway"
    dns:
      - 8.8.8.8
      - 8.8.4.4
    restart: unless-stopped

Then restart the container:

docker compose down
docker compose up -d

This entry is included automatically in installations from v0.9.22 onwards.

Connection refused — Ollama not listening on all interfaces​

Ollama is running but only accepts connections on 127.0.0.1 (the Windows loopback). Docker containers connect from a different network interface and are refused.

Fix: Set the OLLAMA_HOST environment variable to 0.0.0.0:

  1. Search Windows for "Edit the system environment variables" and open it.
  2. Click Environment Variables… → System variables → New.
  3. Name: OLLAMA_HOST / Value: 0.0.0.0.
  4. Click OK, then right-click the Ollama system-tray icon → Quit, and relaunch Ollama.

Verify with:

netstat -ano | findstr ":11434"

You should see TCP 0.0.0.0:11434 LISTENING.

Max retries exceeded / connection timeout — Firewall blocking port 11434​

Ollama is listening on all interfaces but Windows Firewall is blocking inbound traffic on port 11434 from Docker's virtual network adapter.

Fix: Add an inbound firewall rule. Open PowerShell as Administrator:

New-NetFirewallRule `
  -DisplayName "Ollama — Docker access" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 11434 `
  -Action Allow

Retry the Fetch and Test Connection buttons in Settings → AI Provider → Ollama.

Diagnosis command​

If you are unsure which error applies, run this from PowerShell to test connectivity directly from inside the Docker container:

docker exec -it conio-app-1 curl http://host.docker.internal:11434/api/tags

(Replace conio-app-1 with your container name — run docker ps to find it.)

  • JSON response → Ollama is reachable. The issue is inside the app configuration.
  • Connection refused → OLLAMA_HOST=0.0.0.0 is not set or Ollama has not been restarted.
  • Name or service not known → extra_hosts is missing from docker-compose.yml.
  • Timeout / no output → Windows Firewall is blocking the connection.

Facet matching flag is greyed out​

This is by design. The checkbox is disabled until you validate that facets are populated on both your BOQ items and your rate table items. Use the Test Sandbox → Experimental → Facet matching toggle to test on a single item. If scores improve with facets enabled, contact support to enable the flag for your project.

Data & exports​

Garbled characters in exported CSV​

The CSV is BOM-encoded for Excel. If you open it in a text editor or import it into a non-Microsoft tool, you may see a  prefix. This is the UTF-8 BOM and can be ignored or stripped.

Missing resources in a generated URA (rate = 0)​

The AI named a resource that does not exist in your price book. Options:

  1. Add the resource to the price book with the exact name the AI used, then re-generate or manually enter the rate.
  2. Edit the resource name in the URA workspace to match an existing price book entry — the rate will resolve automatically.