Skip to content
VediramVediramSupport
Browse docs

Startup Doctor checks

startupdoctorinstallation

What you see

  • When you open the Levee app, a window titled "Levee can't start cleanly" lists one or more problems.
  • Or an amber banner at the top of the app reports a smaller problem, for example "Preparing container runtime... 40%".

Why it happens

Every time the Levee app opens, its Startup Doctor checks that your computer can run projects. There are two kinds of problem:

  • Blocking problems open the window. You cannot start a project until they are fixed.
  • Smaller problems show an amber banner. Levee still works, sometimes with a feature missing.

Before it shows you anything, the app already tries the obvious repair, such as starting a stopped service.

What you can try

  1. If a problem has a Fix button, click it.
  2. Click Re-run checks.
  3. If the banner says "Preparing container runtime...", wait. Levee is downloading what it needs, usually on first use. Projects can start when it reaches 100%.
  4. Restart your computer, then open Levee again.
  5. If the window still appears, click Copy details for IT and send the copied text to your IT team. It contains what they need: your computer, your Windows version, the Levee versions, and for each problem the technical cause and the recommended fix.

Most fixes need an administrator. Some, such as turning on a Windows feature, also need a restart.

For your IT team

The same checks are available from the command line:

levee doctor

It prints lines such as Engine running:, Containers feature:, Disk sufficient:, Image present:, Provisioning: and Ready:. A failing line shows NO. Add --json for machine-readable output.

Each check below shows its ID and the title the user sees.

Blocking checks

service.installed: "Levee is not fully installed"

The LeveeService Windows service is not registered. The installation is incomplete or was partly removed.

Fix: Reinstall Levee (run the MSI again, or redeploy it through your software distribution tool).

service.running: "Levee service is not running"

LeveeService is installed but stopped. The Fix button tries to start it. From an elevated PowerShell:

Start-Service LeveeService
Get-Service LeveeService, LeveeContainerEngine

If it will not start, repair or reinstall Levee and check the Windows Event Log (Windows Logs > Application) for errors from the service.

service.connected: "Can't reach the Levee service"

The service is running, but the app cannot talk to it. It may be starting up, hung, or have crashed. Fix reconnects.

Restart-Service LeveeService

If the problem persists, repair or reinstall Levee.

version.match: "App and service versions don't match"

The Levee app and the Levee service come from different releases. This happens when only one part was updated, or a repair was interrupted. The installer always updates both together.

Fix: Reinstall the current Levee MSI so the app and the service are the same version.

If the title is "Couldn't verify the Levee version", the service was unreachable. Fix service.running or service.connected first.

engine.running: "Container engine is not running"

Levee ships its own private container engine, installed as the LeveeContainerEngine service. It is not running, is missing, or starts and exits immediately.

  • If it is stopped, Fix starts it, or run Start-Service LeveeContainerEngine from an elevated PowerShell.

  • If it starts and exits immediately, restarting will not help. Repair or reinstall Levee and look in the Windows Event Log for errors with source docker:

    Get-WinEvent -FilterHashtable @{ LogName = 'Application'; ProviderName = 'docker' } -MaxEvents 20 |
    Format-List TimeCreated, LevelDisplayName, Message

  • Make sure the Windows Containers feature is enabled (next check).

Levee does not use or change Docker Desktop or any other container engine on the machine.

engine.feature: "Windows 'Containers' feature is off"

Levee needs the Windows Containers optional feature. The installer does not enable it, and repairing Levee does not either.

Fix: If the Levee app is running as administrator, the Fix button enables the feature. Otherwise, from an elevated PowerShell:

Enable-WindowsOptionalFeature -Online -FeatureName Containers -All -NoRestart
Restart-Computer

A restart is required. Hyper-V is not required. To enable the feature across a fleet, see Planning.

disk.sufficient: "Not enough free disk space"

The system drive does not have enough free space for the container runtime. The technical details show how much is free.

Fix: Free space on the system drive. Levee keeps a safety margin of free space when preparing the runtime (20 GB by default, adjustable with the runtimeProvisioning.diskHeadroomBytes policy setting). See System requirements.

image.present: "Container image is missing"

The runtime image that sandboxes run on is not installed, or the last attempt to prepare it failed. The technical details include the failure reason.

Fix: Levee downloads the image again from downloads.vediram.com the next time it starts. If it keeps failing, check that the machine can reach downloads.vediram.com over HTTPS, then repair or reinstall Levee. See Runtime image won't download.

Smaller problems (amber banner)

runtime.provisioning: "Container runtime provisioning"

Shown as "Preparing container runtime... N%". Levee is downloading, verifying, expanding or loading the runtime image, usually on first run. No action needed. Projects can start when it reaches 100%.

image.update: "Container image update available"

A newer runtime image has been published. Levee never switches images on its own, so running projects are not disrupted. You decide when to move to the new image. See Container runtime.

subsystems.degraded: "Some Levee features are unavailable"

A non-essential part of Levee failed to start for this session. Levee still runs sandboxes. The technical details name the affected part, for example WebIdentityStore (connected identities), UpstreamCredentialStore (package registry credentials), Tools or McpPlugins (plugins). McpPlugins also appears while the plugin list from cloud policy could not be saved to disk; Levee retries at every policy sync and clears it once the write succeeds.

Fix: Restart the service. If it happens again, check the Windows Event Log and the service log for the named part, and repair Levee.

Restart-Service LeveeService
levee log tail --component service --since 1h --level Warning

Before you open a request

Use Copy details for IT, then follow Collecting logs for support.