Help

Troubleshooting

The problems people actually hit with Solon, in the order they meet them, and what to do. Each takes a minute. If yours is not here, the diagnostic export at the bottom is the fastest way to get it fixed.

Windows blocks the installer (SmartScreen)

A blue “Windows protected your PC” screen appears when you run Solon_x.y.z_x64-setup.exe.

  1. Click More info, then Run anyway. The screen means the installer is not code-signed yet, not that it is harmful.
  2. If you want to be sure of what you run: compare the file's SHA-256 with the one published next to the release (Get-FileHash .\Solon_x.y.z_x64-setup.exe in PowerShell). The home page shows it too.
  3. Some antivirus products quarantine unsigned installers: restore the file and add an exception for it before running it again.

Code signing through the SignPath Foundation has been requested; releases will be signed as soon as the project is accepted, and this screen will disappear.

The engine does not start after installation

Solon shows “Engine failed to start” with a code such as WINDOWS_FEATURE_MISSING, HYPERVISOR_NOT_RUNNING or VIRTUALIZATION_DISABLED_IN_FIRMWARE.

  1. Reboot first. The installer enables Hyper-V and the Virtual Machine Platform when they were off; they only work after a restart. Most first-start failures end here.
  2. If the code is VIRTUALIZATION_DISABLED_IN_FIRMWARE: enable hardware virtualization in the BIOS/UEFI (called Intel VT-x, AMD-V or SVM, usually under Advanced, CPU or Security), save, reboot.
  3. Windows Home is supported since 0.1.12: the installer enables the Virtual Machine Platform and asks for one restart. Solon needs Windows 10 22H2 or 11, any edition.
  4. If the code is HYPERVISOR_NOT_RUNNING: an old VirtualBox or VMware, or a bcdedit setting, turned the Windows hypervisor off. Remove or update them (VirtualBox ≥ 6.1, VMware ≥ 15.5), then in an administrator PowerShell: bcdedit /set hypervisorlaunchtype auto and reboot.
  5. Still stuck: Settings → Diagnostic → Export a diagnostic, and open a bug report with the zip (see below).

A stack refuses to start: a port is already in use

Up fails and the output says “port is already allocated” or “address already in use”, or Solon says “Port 8080 is already in use on this PC”.

  1. Another program (another stack, IIS, a dev server, Docker Desktop) already listens on that port. Solon names the port and proposes the next free one: click Use 8081 instead in the gallery, or in the project's Compose tab change the host port (the left number in "8080:80") and click Save and Up.
  2. You may not need a published port at all: every container answers at https://<name>.solon.local, port or not. Comment the ports: lines and use that address.
  3. Two copies of the same stack (two WordPress, two Odoo) always collide on the same port: give the second one another host port, or drop the ports and use the two solon.local addresses.

A container “does nothing” or stops at once

You click Run or Start, the container appears for a second and goes to Exited; hello-world is the classic case.

  1. That is normal for a program that does its job and quits: hello-world prints its message and exits in a tenth of a second. Solon opens its logs and shows “exited immediately with code 0”; the message is in the Logs tab.
  2. A server that exits with a non-zero code is a real failure: read the last lines of its logs (Logs tab, or docker logs <name>). The usual causes are a missing environment variable, a wrong volume path or a port the container itself cannot bind.
  3. A container that Solon put to sleep (moon icon) is not stopped: the next request wakes it. Use Keep awake on its page if it runs scheduled tasks.

No network in the containers, or a solon.local address does not open

apt or pip time out inside a container, or the browser cannot reach https://name.solon.local.

  1. Corporate VPN. Some VPN clients (AnyConnect, GlobalProtect, Zscaler) block traffic to virtual adapters. Disconnect the VPN and try again; if it works, add it to your bug report so a workaround can be found.
  2. The address. A container has an address only while it runs; the name is the container's (web.solon.local) or service.project.solon.local for Compose. Open http://anything.solon.local: the page lists every address currently available.
  3. The certificate. Browsers and .NET trust the local certificates. curl.exe on Windows needs --ssl-no-revoke, like with mkcert.
  4. Links that point to http://. WordPress, Nextcloud and friends generate links from the request: Solon passes X-Forwarded-Proto: https, which the official images honour. For an existing WordPress installed over http, update the site URL in Settings → General.
  5. The hosts file. Solon writes the names into C:\Windows\System32\drivers\etc\hosts between # solon-begin and # solon-end. A security product that protects that file blocks the addresses: allow Solon or add the names by hand.

The disk fills up

Windows warns that drive C: is almost full, or Solon shows “Engine disk almost full”.

  1. Solon keeps everything in one file, %ProgramData%\Solon\data.vhdx, which grows with images, containers and volumes and only shrinks after a clean-up.
  2. Settings → Disk → Reclaim space: removes the images no container uses and the build cache, then gives the freed space back to Windows. Containers and volumes are never touched.
  3. Still large? Images → “Unused only” shows what remains; Volumes → “Unused only” shows volumes no container references (data you may want to keep: check before removing).

Docker Desktop or WSL is also installed

docker commands talk to the wrong engine, or Docker Hub refuses your login.

  1. Solon and Docker Desktop can coexist. Which engine the docker command talks to depends on which docker.exe comes first in your PATH; Solon's is in its installation folder. docker context ls shows the current one.
  2. Docker Hub “unauthorized” errors: the Windows docker CLI reuses credentials stored by Docker Desktop, which may be stale. docker logout then docker login fixes it.
  3. WSL is not used by Solon and does not need to be installed or removed.

Report a problem

One zip file tells more than a screenshot. It takes ten seconds.

  1. In Solon: Settings → Diagnostic → Export a diagnostic…, save the zip.
  2. Open a bug report on GitHub and drop the zip into the form, with what you did and what you expected.
  3. Mention your Windows version (winver), whether a VPN, another antivirus, Docker Desktop or WSL are present.

The zip contains Solon's logs, its state and settings, the prerequisites report, docker info and the versions. It does not contain your containers' data, passwords or Docker Hub credentials; you can open it and check before sending.

Open a bug report

Error codes

Every error shown by Solon carries a stable code. Logs are in %ProgramData%\Solon\logs and can be copied from the error screen.

CodeCauseWhat to do
VIRTUALIZATION_DISABLED_IN_FIRMWARE VT-x / AMD-V disabled Enable virtualization in the BIOS/UEFI (Advanced, CPU or Security tab), reboot.
WINDOWS_FEATURE_MISSING Hyper-V or Virtual Machine Platform disabled Reboot if you just installed. Otherwise reinstall Solon (the installer enables them) or, in an administrator PowerShell: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V,VirtualMachinePlatform -All, then reboot.
WINDOWS_FEATURE_BLOCKED_BY_POLICY Company policy (WSUS, GPO) refuses the feature Ask your administrator to enable Microsoft-Hyper-V and VirtualMachinePlatform.
HYPERVISOR_NOT_RUNNING Windows hypervisor not started Uninstall old VirtualBox/VMware (< 6.1 / < 15.5), check bcdedit /enum (hypervisorlaunchtype Auto), do not run Solon in a VM without nested virtualization.
HOST_COMPUTE_SERVICE_UNAVAILABLE vmcompute or hns service stopped or missing Reboot Windows; otherwise reinstall Solon.
BLOCKED_BY_SECURITY_SOFTWARE Antivirus / EDR blocks the disks or the service Add %ProgramData%\Solon and the installation folder to the exclusions.
INSUFFICIENT_PRIVILEGES The service does not run with the expected rights Reinstall Solon (the service must run as LocalSystem).
IMAGE_CORRUPTED Engine files missing or SHA-256 mismatch Reinstall Solon.
DATA_DISK_ERROR data.vhdx cannot be created or opened Check disk space and antivirus exclusions; as a last resort rename %ProgramData%\Solon\data.vhdx (loses Docker data).
VM_BOOT_TIMEOUT, AGENT_UNREACHABLE, ENGINE_UNREACHABLE The machine does not answer Restart the engine; read solon-service.log; report with the diagnostic zip.
No network from containers Corporate VPN or IP range conflict Solon picks a free range and sets the MTU to 1400; some VPNs still block virtual adapters: disable the VPN to test, then report.
“The Solon service is not running” Service stopped sc start SolonService as administrator, or reinstall.

Power loss or hard shutdown: at the next start Solon checks and repairs the data disk (fsck), then restarts the engine. Unsynced writes of the last two seconds may be lost, as on any Linux machine.

← Back to the home page