Table of Contents
- Troubleshooting
- Install and update
- The installer stopped part way
- update says "Done, with errors in: …"
- "could not pull the latest CoreDesktop"
- "Only N GiB free on /"
- "Don't reboot yet: the initramfs failed to rebuild"
- A GNOME extension is missing or doesn't load
- Configure
- Tailscale: "failed to connect to local tailscaled"
- Nextcloud files
- Nextcloud says the password is wrong
- AI agents
Troubleshooting
Install and update
The installer stopped part way
Run it again: each step skips what's already done. The usual causes are a sudo password timing out or a network hiccup.
update says "Done, with errors in: …"
Scroll up to that step's output. Each step runs on its own, so the rest of the update still happened. Common ones:
| Step | Usual cause |
|---|---|
10-pacman.sh |
An Arch change that needs a manual step. Check the "Latest News" on https://archlinux.org. |
12-migrations.sh |
A one-time change failed. It's retried on every update, and later migrations wait for it. The output says which one failed. |
20-aur.sh |
An AUR package failed to build. It usually fixes itself when the package is updated. |
71-siblings.sh |
A sibling project couldn't pull, or its update.sh failed |
"could not pull the latest CoreDesktop"
The CoreDesktop folder has local changes. version shows "modified" when this is the case. To see them:
git -C ~/.local/share/coredesktop status
Keep anything you need elsewhere, then discard the changes:
git -C ~/.local/share/coredesktop checkout -- .
"Only N GiB free on /"
update needs 10 GiB free, because an upgrade that runs out of space can leave the system half-upgraded. Free up space, for example with sudo paccache -rk1. If you're sure, run UPDATE_FORCE=1 update.
"Don't reboot yet: the initramfs failed to rebuild"
Rebooting now could leave the machine unbootable. Read the errors in ~/.local/state/coredesktop/pacman-update.log and fix them first. If a reboot does fail, roll back to the snapshot taken before the update (see Updating).
A GNOME extension is missing or doesn't load
GNOME only loads new or updated extensions at login, so log out and back in first. If an extension still isn't there, check:
~/.local/bin/gext list
gnome-extensions info <extension-id>
If gext itself fails with ModuleNotFoundError, a Python upgrade broke it. update reinstalls it.
Configure
Tailscale: "failed to connect to local tailscaled"
The Tailscale service isn't running. configure starts it now. On older versions, start it yourself and run configure core again:
sudo systemctl enable --now tailscaled
Nextcloud files
If /mnt/<domain> is empty, first check whether it's mounted:
mountpoint /mnt/<domain>
mount /mnt/<domain>
| Message | Fix |
|---|---|
user <you> must be member of group network |
configure added you to the network group, but it only takes effect at your next login. Log out and back in, or for now run sudo -u $USER mount /mnt/<domain>. |
| Asks for a password, or 401 errors | The app password was revoked or is wrong. Run configure core again. |
| Mounted, but empty | Check the WebDAV address in /etc/fstab. It should end with /remote.php/dav/files/<your user>. |
The folder is mounted when you log in to the desktop. If the network wasn't up yet, it won't be mounted; run mount /mnt/<domain>.
Nextcloud says the password is wrong
configure checks your Core password against Nextcloud and gives you three tries. If you use two-factor sign-in, Nextcloud may refuse the password itself. In that case, create an app password in Nextcloud under Settings > Security and enter that instead.
AI agents
"Start from a project directory"
A sandboxed agent can change anything in the directory it starts in, so it refuses to start in your home folder or /. cd into a project first.
An agent can't reach a site or write a folder
The sandbox blocked it. Add the domain or folder as shown in Sandboxed AI Agents.
"The sandbox (srt) isn't installed"
Run update. To use the agent without the sandbox in the meantime, run unsandboxed <agent>.
Using CoreDesktop
Working on CoreDesktop