Troubleshooting¶

Solutions to common Bootible issues.

Bootstrap Issues¶

Script Download Failed¶

Symptom: curl: (6) Could not resolve host: bootible.dev

Solutions:

1. Check internet connection
2. Try a different DNS: curl --dns-servers 1.1.1.1 ...
3. Download manually and run locally

Permission Denied¶

chmod +x deck.sh
./deck.sh

GitHub Authentication Failed¶

Symptom: QR code flow fails or times out

Solutions:

1. Ensure you have internet access
2. Try the code manually at github.com/login/device
3. Clear browser cache and try again
4. Wait a few minutes and retry (rate limiting)

Steam Deck Issues¶

Decky Not Showing in Quick Access Menu¶

Solutions:

1. Restart Steam: Hold Power > Restart Steam
2. Reinstall Decky: Re-run bootible
3. Check install:

   ls ~/homebrew/plugins/
   

4. Check Decky service:

   systemctl --user status plugin_loader
   

Flatpak Install Failed¶

Symptom: App installation errors

Solutions:

1. Update Flatpak:

   flatpak update
   

2. Check Flathub:

   flatpak remote-list
   

3. Add Flathub if missing:

   flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
   

4. Check app ID is correct - search on Flathub.org

SSH Connection Refused¶

Solutions:

1. Check service:

   systemctl status sshd
   

2. Start if stopped:

   sudo systemctl enable --now sshd
   

3. Check firewall:

   sudo firewall-cmd --list-all
   

4. Verify port:

   ss -tlnp | grep ssh
   

Ansible Errors¶

Symptom: Playbook fails with red error text

Common Causes:

1. Wrong sudo password: Re-run and enter correct password
2. Network timeout: Retry - temporary network issue
3. Package not found: Check Flatpak app ID is correct
4. Permission denied: Ensure --ask-become-pass is used

Debug Mode:

ansible-playbook playbook.yml --ask-become-pass -vvv

SteamOS Update Broke Things¶

SteamOS updates can reset:

• Decky Loader
• Pacman packages
• Some system configs

Solution: Re-run Bootible

bootible

Flatpak apps and your config survive updates.

ROG Ally Issues¶

Winget Not Working¶

Solutions:

1. Update App Installer:
2. Open Microsoft Store > Library > Update all

3. Search "App Installer" and update

4. Reset sources:

   winget source reset --force
   

5. Reinstall winget:

   Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe
   

Package Install Failed¶

Symptom: Specific package fails to install

Solutions:

1. Run dry-run to validate:

   .\Run.ps1 -DryRun
   

2. Try manual install:

   winget install PackageId --accept-source-agreements
   

3. Check exact package ID:

   winget search "package name"
   

Registry Changes Not Applied¶

Symptom: Settings don't take effect

Solutions:

1. Sign out and back in - some HKCU changes need this
2. Check scheduled task - UCPD-protected keys use scheduled tasks
3. Restart - some changes require reboot

SSH Not Working¶

Solutions:

1. Check OpenSSH installed:

   Get-WindowsCapability -Online | Where-Object Name -like '*OpenSSH*'
   

2. Check service:

   Get-Service sshd
   

3. Start service:

   Start-Service sshd
   Set-Service sshd -StartupType Automatic
   

4. Check firewall:

   Get-NetFirewallRule -DisplayName "*SSH*"
   

PowerShell Script Blocked¶

Symptom: "Running scripts is disabled on this system"

Solution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Configuration Issues¶

Invalid YAML Syntax¶

Symptom: "yaml: line X: mapping values are not allowed"

Common Causes:

1. Missing colon after key:

   # Wrong
   install_discord true
   
   # Correct
   install_discord: true
   

2. Incorrect indentation:

   # Wrong (inconsistent spaces)
   static_ip:
     enabled: true
       address: "1.2.3.4"
   
   # Correct
   static_ip:
     enabled: true
     address: "1.2.3.4"
   

3. Quotes missing around special characters:

   # Wrong
   hostname: my-deck!@#
   
   # Correct
   hostname: "my-deck"
   

Type Validation Errors¶

Symptom: "expected bool, got string"

Common Mistakes:

Config Not Being Applied¶

Checklist:

1. File is in correct location?

2. private/device/<platform>/<instance>/config.yml

3. Device instance selected correctly?

4. Check prompt during bootstrap

5. YAML is valid?

6. Use online YAML validator

7. Values are correct type?

8. Check validation output

Network Issues¶

Can't Reach Device¶

Checklist:

1. Same network?
2. IP address correct?
3. Firewall allowing connections?
4. Service running on device?

Find device IP:

hostname -I

ipconfig | findstr "IPv4"

Static IP Not Working¶

Solutions:

1. Verify network connection name - use exact name from nmcli con show or Get-NetAdapter
2. Check for typos in IP address format
3. Ensure gateway is correct - usually your router's IP
4. Check no IP conflict - another device using same IP?

Tailscale Can't Connect¶

Solutions:

1. Re-authenticate:

   tailscale down
   tailscale up
   

2. Check status:

   tailscale status
   

3. Firewall blocking? - Tailscale needs UDP 41641

Emulation Issues¶

EmuDeck Won't Run¶

Solutions:

1. Double-click the desktop shortcut (not the file)
2. Check it's executable:

   chmod +x ~/Desktop/EmuDeck.desktop
   

3. Download fresh:

   curl -fsSL https://www.emudeck.com/EmuDeck.desktop -o ~/Desktop/EmuDeck.desktop
   

ROMs Not Appearing in Steam¶

Checklist:

1. ROMs in correct folder? (check ~/Emulation/roms/<system>/)
2. Ran Steam ROM Manager?
3. Clicked "Save to Steam"?
4. Restarted Steam?

Emulator Performance Issues¶

General Tips:

1. Lower resolution/upscaling
2. Disable enhancements
3. Check TDP isn't limited (PowerTools)
4. Use performance power profile
5. Close background apps

Backup & Recovery¶

Steam Deck: Restore from Snapshot¶

# List snapshots
sudo ls /home/.snapshots/

# Restore (requires root)
sudo btrfs subvolume delete /home
sudo btrfs subvolume snapshot /home/.snapshots/bootible-pre-setup-XXXXX /home

ROG Ally: System Restore¶

1. Search "Create a restore point" in Start
2. Click "System Restore"
3. Select the Bootible restore point
4. Follow wizard

Getting Help¶

If these don't solve your issue:

1. Check logs — Steam Deck: ~/bootible/private/device/steamdeck/<name>/Logs/ · ROG Ally: PowerShell transcript
2. Search existing issues — GitHub Issues
3. Open new issue with device/OS version, config snippet (remove secrets!), full error, and steps to reproduce