Troubleshooting Companion OS
Find what you see in the left column, then read what it means. Many rows are things that look wrong and are normal.
Companion OS is in beta, with current testing performed in virtual machines. Rows about Wi-Fi, Bluetooth, sound, and graphics cards describe recommended steps to try on physical hardware.
Starting from the USB stick
| What you see | What it means and what to do |
|---|---|
| The firmware does not list the stick | Write the image again and verify the write (see Install Companion OS from a USB stick). Try another USB port. Ensure the machine starts in UEFI mode, not CSM. |
| The machine refuses to start from the stick | Turn Secure Boot off in the firmware settings and try again. |
| Text scrolls for a while before the desktop appears (arm64) | Wait. On arm64, boot messages stay on screen until the desktop is ready (about two minutes in a virtual machine). |
| A window says “Welcome to Ubuntu” on the live desktop | Canonical’s standard installer opened automatically. Close it, then select Install Companion OS (automatic) in the dock, or choose the standard installer icon there. |
Installing
| What you see | What it means and what to do |
|---|---|
| ”No internal disk of at least 25 GB was found” | The machine has no internal disk of at least 25 GB, or the only candidates are removable USB/SD drives or the installer stick itself. Use a larger internal disk or the standard installer. |
| ”An installation is already running, or an earlier one left the new system mounted” | The installer did not change your disk. If no installation is active, restart from the stick and try again. |
| ”The automatic install did not finish”, with “Nothing was erased.” | The dialog states whether the installer modified the disk. Check /var/log/installer/ in the live session for details. |
| You lost the one-time password | The installer shows the password in the confirmation dialog and in the progress window. If you lose it before your first sign-in, run the installation again. |
| My language is not in the Language list | The one-click installer includes offline packs for German, English, Spanish, French, Italian, Portuguese, Russian, and Chinese. The standard installer lists more languages and downloads their packs over the network. |
| My keyboard variant (dead keys, Dvorak, “intl”) is not offered | The one-click list shows base layouts only. Pick the base layout now, then select the variant after installation in Settings, Keyboard. |
| The language list suggested a keyboard I did not want | Choosing a language suggests a matching keyboard layout. Choose Keyboard, pick another layout, and select Done. A layout you pick manually stays in place even if you change the language afterward. |
| The time zone says Detect automatically | The installer looks up your time zone over the network, or falls back to UTC when offline. To skip the network lookup, pick a time zone from the list. |
The first start
| What you see | What it means and what to do |
|---|---|
| The sign-in asks for a “current password” and then a new one | Normal. Enter the one-time password once to set your own password. |
| A notification says “Setting up Companion OS: step 3 of 7” | Normal. The first-time setup runs in the background while the desktop remains usable, and finishes with “Companion OS is ready”. Open Companion Hub from the dock once it finishes. |
| The step numbers skip (3, then 5, then 7) | Normal. When a step finishes quickly, the notifier skips its banner. |
| No notification about the setup | Do Not Disturb hides banners, though notifications remain in the top-bar list (select the clock). The first banner appears at sign-in. Older images and the live USB session do not show setup notifications. |
| The screen went dark and asks for my password during the first start | After five minutes of inactivity, Ubuntu blanks the screen and locks the session while background setup continues. Unlock with your password and select the clock at the top of the screen to see the completion message. |
| The notification text is English, but I chose another language | Setup notifications are currently in English only; the rest of the desktop uses your selected language. |
| ”Companion OS is waiting for the internet” | The network connection is not ready yet. This message can appear briefly during startup before giving way to the setup steps. If the machine is offline, connect to a network from the top-right menu and the setup will continue automatically. |
| ”Companion OS setup needs attention” | A setup step stopped. The service retries automatically on its timer. To retry immediately, run sudo ci-os-setup, and check ci-os-info to see which step failed. |
| A second browser tab says “Firefox Privacy Notice” | Normal on older images; newer images open only the Companion welcome page. That tab is Firefox’s built-in first-run page. |
| A notice says “80 Updates Available” (the number varies) | Normal on older images; newer images suppress this pop-up. The ISO carries the package versions from its build date. To install updates immediately, run sudo apt update && sudo apt upgrade. |
systemctl --failed lists pd-mapper.service, and the system reads “degraded” (arm64) | Known and harmless on machines that are not Qualcomm Snapdragon laptops. It does not affect Companion Hub. |
| Companion Hub opens on “Step 1: Get your pairing code” | Normal. Pair Hub with your CI Account to complete setup. See First login and setup. |
| Companion Hub shows an error or nothing in the first minutes | Wait a minute, then reload. Run docker ps to verify that ci-hub, ci-hub-db, and ci-hub-queue report healthy. If the containers are missing, run sudo ci-os-setup. |
The terminal says Docker needs sudo | Sign out and sign back in so your docker group membership takes effect, or run newgrp docker in the current shell. |
The setup log
/var/log/ci-os-first-boot-setup.log records the full first-boot transcript. Images built before 20 October 2026 log several harmless lines that newer images omit:
| Line | Why you can ignore it |
|---|---|
CI-Hub not deployed: REGISTRY_USERNAME/REGISTRY_PASSWORD not set | The setup script starts Hub from the public image a few lines later. |
Note: 'Create deploy read key' step was not specified | An unused build step note; no action is required. |
gsettings not available or no valid user detected | The background service runs outside a desktop session, so it skips gsettings. |
Log out and back in for Docker group and PATH changes | Only needed if a terminal command reports a Docker permission error. |
A successful run ends with Hub started successfully and the final setup completion line.
Models and Hub
| What you see | What it means and what to do |
|---|---|
ollama list is empty | The setup has not finished or had no network connection. Check /var/log/ci-os-first-boot-setup.log, verify your network connection, and run sudo ci-os-setup. |
The big model qwen3.6:27b is not there | Expected on most machines. The first-boot script pulls qwen3.6:27b only on AMD unified-memory systems (Ryzen AI Max class) with at least 30 GB of RAM. See Choose hardware for Companion OS. |
| The disk is filling up | Models and Docker images use the most space. Run ollama list and ollama rm <model> to remove unused models, and run docker system df to inspect Docker disk usage. |
Network and remote access
| What you see | What it means and what to do |
|---|---|
| Another device cannot open Hub | Open http://<machine-ip>:5002 using the machine’s LAN IP address. Confirm that both devices are on the same network and that curl http://localhost:5002/ succeeds on the machine itself. |
companion-os.local does not work | The machine advertises companion-os.local over mDNS. On the machine itself, the name can resolve to a Docker bridge address (172.x.x.x), which is harmless. If your network or client device does not resolve .local names, use the machine’s IP address instead. |
| You want to reach the machine away from home | Use the pre-installed Tailscale client (sudo tailscale up). Do not forward ports on your router. See After you install Companion OS. |
Hardware
| What you see | What it means and what to do |
|---|---|
| No Wi-Fi, no Bluetooth, or no sound | Run sudo apt install linux-firmware and restart. If the device still does not work, run lspci and lsusb and include the output in a support report. |
| A graphics card is not used for models | Companion OS does not pre-install NVIDIA drivers. On the Ubuntu image, run sudo ubuntu-drivers install and restart so Ollama can detect the GPU. |
Report a problem
Collect what we need into one file, read it, and attach it to your report. It is not meant to hold passwords, and it does contain your machine’s name, so read it before you share it:
{
ci-os-info
echo; systemctl --failed --no-legend
echo; docker ps --format '{{.Names}} {{.Status}}'
echo; ollama list
echo; tail -n 60 /var/log/ci-os-first-boot-setup.log
echo; lspci; lsusb
} > ~/companion-os-report.txt 2>&1Say which image you installed (the file name, and its checksum if you have it), what the machine is, and what you saw. Report it at ci.computer/support or in the community chat.
Last updated on