Tilo

Troubleshooting

Write down the exact message on screen and what you did immediately before it appeared. If the message includes an error code, keep that too.

The virtual machine does not start

Use the virtual-machine guide and check:

  1. The installer image matches the virtual machine’s processor architecture.
  2. Its checksum matches the value on the download page.
  3. Hardware virtualisation is enabled if the VM application requires it.
  4. The VM has UEFI firmware, at least 4 GB of memory, and a blank destination disk of at least 40 GB.
  5. Shared folders, clipboard integration, USB devices, and physical host disks are disconnected while you diagnose startup.

Tilo does not publish prepared VirtualBox or UTM bundles. Create a custom VM from the verified raw installer image. Deleting the VM also deletes anything stored only on its virtual disk.

The live USB does not start

  1. Verify the image and write it again without a multi-boot USB tool.
  2. Try another USB drive and port.
  3. Choose the UEFI entry for the drive in the firmware’s one-time boot menu.
  4. If the boot menu offers Basic graphics, try it.

Do not disable Secure Boot merely because an unrelated guide suggests it. A release that needs a firmware change will explain why on its download page and tell you how to undo it.

The Tilo session is missing from sign-in

Sign in to the desktop that already works, then:

  1. Check that the Tilo package installation completed without an error.
  2. Install pending distribution updates and restart the computer.
  3. Confirm that the sign-in screen uses a supported Wayland display manager.
  4. Repeat the package check in the relevant Fedora, Ubuntu or Debian, Arch, or NixOS guide.

If Tilo opens to a blank screen, return to a text console with Ctrl + Alt + F3, sign in, and save the error shown by the session. Restart and select the previous desktop from the session menu.

Installation stopped

Leave the USB inserted and record the last error. Do not immediately repeat a format or whole-disk installation: the destination may already have changed.

If the disk still contains files you need, recover those files before trying again. Boot the Tilo installer, press Ctrl + Alt + F2, and use Tilo recovery tools to open the Tilo partition read-only and copy files to a mounted drive on another physical disk.

The complete system no longer reaches sign-in

If the boot menu offers a previous Tilo image, try it once. A new image that fails to reach sign-in three times should automatically give way to the previous one.

If no normal image starts, choose Tilo Repair Mode to inspect the previous boot, try another deployment, or copy files without starting the desktop. If the system image itself cannot mount, boot the matching Tilo installer and press Ctrl + Alt + F2. An encrypted installation requires its recovery key or disk passphrase.

The disk asks for its recovery key

A firmware update, TPM clear, Secure Boot change, or motherboard replacement can trigger recovery even when the usual PIN is correct. Enter the recovery key you saved during installation.

Do not approve a new trusted firmware state if you did not expect the change. Recover important files first and investigate from another trusted device.

An app cannot see a file or device

Check the workspace’s Permissions page before changing ownership, exposing the whole home directory, or running the app as root.

  • Select the file again with the system file chooser or drag it into the app.
  • For camera, microphone, location, screen capture, or broad network access, check the grant and its duration.
  • Confirm that the app is open in the intended workspace.

A denied permission is a normal result. An app that asks for unrelated access should be treated as faulty, not granted everything.

Collaboration does not connect

  1. Confirm that both devices show the correct time and use compatible versions.
  2. Create a new invite and check its workspace name and expiry.
  3. Confirm that the inviter is still allowed to invite people.
  4. If a laptop hosts the workspace, keep it awake and online.
  5. Try another network if guest Wi-Fi blocks direct and relay connections.

Connection details may contain endpoint and relay identifiers. They should not contain workspace files, collaborator content, or the invite secret.

Stop remote input

Press Super + Esc. Your keyboard and pointer take priority. Then open People to disconnect the person or remove access, and review History for changes made during the session.

Stopping input does not recall files that another device already received.

A workspace is missing

Open Workspace details and look for a device or host with a complete copy. Bring that device online and sync again. If this computer has the last complete copy, export or back it up before clearing caches or removing Tilo.

If you have a snapshot, open the separate Backups app, select it, run Verify, and restore into an empty folder. Restore does not overwrite existing files by default. A partial workspace copy cannot recreate files it never downloaded.

Make a useful problem report

Keep the report small and factual:

  • what you tried;
  • what you expected;
  • what happened instead;
  • whether it happens again;
  • the exact error text;
  • the hardware model for boot, graphics, input, suspend, or network problems.

Before sending diagnostics, inspect the files and remove names, paths, workspace content, and secrets. The public issue tracker and in-product reporting route will open with the public alpha. Until then, save the report locally.