Skip to content

Troubleshooting

Jump to bottom
Michael DeGuzis edited this page Jan 5, 2018 · 99 revisions

Table of Contents generated with DocToc

About

This page contains community-driven help for various SteamOS and Steam hardware issues. For most issues, it is asked that you please first check the Steam Universe community discussions (please note the subsections there) before checking this page.

Owners of Steam Machines

Those who have purchased Steam Machines from the likes of Alienware, Syber, Zotac, and so on, don't forget you may still have a support agreement with them! It does not hurt, and it suggested, that you first try to reach out to your vendor the machine was purchased from. Always seek officially sanctioned support if possible, before relying on community troubleshooting.

What to do if you cannot start SteamOS

See: Advanced System Recovery

General SteamOS Issues

Common Installation Issues

See the Common Installation Issues wiki page.

Debugging SteamOS upgrade issues

Investigation

If you still get a message in your inbox saying "Restart to update SteamOS" but no matter how many restarts you perform, and it doesn't seem update beyond your current version, you may have an underlying technical issue. The commands below are a core subset of what is going on when you check for OS updates in SteamOS. See the wiki page on the update process for more.

Review the output from these commands

  • apt-get -s install
  • apt-get -s update
  • apt-get -s dist-upgrade

These commands will simulate (-s) upgrades. --dry-run can be used in place of -s. If you then feel comfortable, remove the -s option to process each command.

Digging further down the rabbit hole

sudo unattended-upgrade -d will run and debug the unattended upgrades in a terminal window. sudo unattended-upgrade --dry-run will simulate the upgrade process for safety. If you choose to do a dry run first, check the logs.

Take note of these logs below:

# /var/log/unattended-upgrades/
unattended-upgrades-dpkg.log  unattended-upgrades-shutdown.log
unattended-upgrades.log       unattended-upgrades-shutdown-output.log

Also check the contents of

/run/unattended-upgrades/ready.json

The upgrades.log file will show the debug-like info for the unattended upgrade. The dpkg log will show apt-get output related information. The shutdown log are more akin to dmesg output. I never see much in the shutdown-output specific log. ready.json will also show what may be causing the issue. This file will show packages to install, upgrade, as well as those that are possibly being held back.

For further reading, please see this entry.

Manually Upgrading

If you hit a black screen after updating, it's possible the unattended upgrade got stuck or packages were held back. Generally these steps can help:

Find and kill the upgrade process as soon as you get the repair screen or use recovery mode

ps -aux | grep repair
sudo kill -9 <PID>

Carefully review and execute a full upgrade

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade

Once you have all packages upgraded (double check the above again), you should be ok to remove old packages:

sudo apt-get autoremove
sudo apt-get autoclean

Reboot:

sudo shutdown -r now

I saw an announcement for an OS update, why don't I have it?

SteamOS update levels depend on 2 things roughly:

  1. If you have steamos-beta-repo installed or not (optional)
  2. The current version of steamos-updatelevel

You can see that here:

desktop@steamos:~$ dpkg-query -W steamos-beta-repo
steamos-beta-repo       2.0+bsos1

As you can see below, my update level should be 2.84, the upgrade just hasn't been done on the target machine yet. In this example, those not in the OS beta channel should still be at 2.70. There is a client beta opt-in and OS-beta opt in. Unless you have a good reason to be in the OS beta, it is suggested to be patient (or if you like being a tester of sorts, have at it).

desktop@steamos:~$ apt-cache policy steamos-updatelevel
steamos-updatelevel:
  Installed: 1:2.70
  Candidate: 1:2.84
  Version table:
     1:2.84 0
        500 http://repo.steampowered.com/steamos/ brewmaster_beta/main amd64 Packages
 *** 1:2.70 0
        150 http://repo.steampowered.com/steamos/ brewmaster/main amd64 Packages
        100 /var/lib/dpkg/status

The "Restart to update SteamOS" flag won't go away!

Do not anything in this section if you have not carefully read through the previous "Debugging SteamOS upgrade issues" entry! This is a last resort and should only be done if you are ensure your system is fully up to date and has been restarted at least once or twice.

This generally occurs after some of kind of disconnect between manually resolving upgrade issues, and what Steam is aware of. This flag is determined by this line of code in /usr/bin/steamos-update:

if [ -f /var/run/reboot-required ] && [ "`pidof -s steam`" != '' ] ; then

Also, check the contents of /run/unattended-upgrades/ready.json:

{
  "autoremovals": [],
  "blacklisted": [],
  "kept_back": [],
  "to_install": {},
  "to_upgrade": {
    "libxapian22": "1.2.19-1+deb8u1"
  },
  "whitelisted": []
}

If a package sticks here, it is advised to:

  1. Remove the offending package, if removal is non-destructive to system packages (use your best judgement here).
  2. Run sudo apt-get update
  3. sudo reboot
  4. After reboot, install the package again, and check for SteamOS updates / Troubleshoot upgrade problems (above).

So, if Steam is running and /var/run/reboot-required exists, a Steam UI flag is displayed. This should be gone after a reboot, but if it isn't then it is suggested you delete it manually. /var/run/reboot-required.pkgs (if present) should tell you which packages required the reboot. As noted above ready.json may hold some information important for debugging as well.

For more information, please the wiki page update-notifications

Gnome-terminal does not launch on SteamOS Brewmaster!

If you still have trouble with this, make sure you correct your locales. You can perform the "fix" in UXTerm. You'll find this under /usr/share/applications. Browse to this with the file folder browser, starting with "computer" for / (root). You could also switch to a different TTY line if you know how to.

sudo dpkg-reconfigure -plow locales

Choose only the locale you wish to generate, such as en_US.UTF-8 for English. On the next screen, select your generated locale that you placed the * asterisk next to. Reboot your installation with:

sudo reboot

SteamOS Doesn't Use The Best Resolution Or Refresh Rate For My Display

Currently(12/23/2015) SteamOS only supports the resolutions 1920x1080 and 1280x720 at a refresh rate of either 60 or 59 hz. Other resolutions and refresh rates are not supported by Valve and require modding SteamOS in ways which might break the automatic updater. You can find out how to do in the Custom Resolutions and Refresh Rates wiki page.

Switching to desktop mode leaves monitor/TV with no signal

SteamOS runs a script which sets the resolution and refresh rate of your monitor, before starting Steam. This script does not run when the desktop mode is launched, allowing the desktop itself to pick a resolution.In some cases this will result in the TV/monitor giving no signal.

If you want to return to Steam, you can hold the home button on your controller or press Ctrl+Alt+F7 on your keyboard.

To make the desktop usable in this situation you'll have to take the following steps:

  • Press Ctrl+Alt+F4
  • Log in with the following username: desktop
  • Create the file we need with a text editor: nano .config/autostart/set_hd_mode.desktop
  • Add the following lines to the file:
[Desktop Entry]
Type=Application
Exec=/usr/bin/steamos/set_hd_mode.sh
X-GNOME-Autostart-enabled=true
Name=sethdmode
  • Now press Ctrl+X to exit the text editor and pick Y to save.
  • Press Ctrl+Alt+F7 to return to Steam.

Now when you launch the desktop, it should work like expected.

Autorepair boot loop

A full explanation of the steamos-autorepair script can be found at the SteamOS auto-repair process wiki page.

The autorepair may kick in because the Steam big picture session fails to start due to a problem with the Steam client. In this case the autorepair process won’t succeed because it doesn’t do any client-related problem fixing.
You’ll end up with a boot loop on the following message:
SteamOS is attempting to recover from a fatal error

If that happens you may try the following steps. The goal is to launch the Steam client manually from a desktop session and let it repair itself.

  • At early boot press Esc repeatedly to reach boot menu
  • Choose Advanced options, and then the first (recovery mode) entry available
    At this stage you should be in front of a root prompt like root@steamos:~#
  • If not done already, create a password for desktop user:
    passwd desktop
    and enter the password twice.
  • Disable automatic login for login manager lightdm:
    sed -i -e "s/^autologin-user=/#\0/" /usr/share/lightdm/lightdm.conf.d/20_steamos.conf
  • Reboot and login as desktop user with the previously set password. Note: If you get an error right after login, see this
  • Open a terminal and launch Steam as steam user: sudo su -c "steam" steam
    Then let the Steam client fix itself.
  • When done, exit Steam and restore automatic login for lightdm:
    sed -i -e "s/^#\(autologin-user=\)/\1/" /usr/share/lightdm/lightdm.conf.d/20_steamos.conf

Error right after login as desktop user

When, during troubleshooting, you get an error immediately after logging in as desktop user, SteamOS is broken. You can repair SteamOS by choosing the "Restore System Partition" item in the bootloader. Important to note is that this will only fix your OS, not the Steam Client itself. It is possible that both your OS and the steam client are broken. Running a broken Steam Client on a restored OS might break the OS again.

To fix this, you need to do the steps described in "Autorepair boot loop" immediately after restoring the system partition. So after restoring the system partition you have to login as "desktop" user without first starting steam normally.

The date / time is not right

For some users, the data/time is wrong for their chosen locale. That issue is documented on the bug tracker here. A simple workaround for now, is to enable the Linux desktop, and enter the Settings control panel to correct the date/time

  1. Open the Activities overview and start typing Date & Time.
  2. Click on Date & Time to open the panel.
  3. If you have Automatic Date & Time set to ON, your date and time should update automatically if you have an internet connection. To update your date and time manually, set this to OFF.
  4. Click Date & Time, then adjust the time and date. You can change how the hour is displayed by selecting 24-hour or AM/PM for Time Format.

Steam Issues

The Steam BPM browser fails to play web content correctly

Netflix specific

See issue #417 for some back story to this. For some users, Netflix reports "Whoops.." error and Netflix refuses to actually stream anything if they try to use it from the browser in SteamOS's normal BPM.

Pierre-Loup from Valve, suggested users go watch a community broadcast in Steam, then it should start working. This has worked for some users to resolve this issue. You can find these in the store, but there are easily viewable from the community section on the main screen.

Other general troubleshooting steps

Those of you still affected could try clearing your browser cache:

cd /home/steam/.local/share/Steam/config/ # change into the directory containing htmlcache
sudo tar cfvz htmlchache.tar.gz htmlcache # create backup
sudo rm -rf htmlcache/* # remove all files
sudo shutdown -r now # reboot system

If content, such as Netflix within the Steam client browser, still throws a "Whoops, something went wrong" error, try playing a Steam game broadcast again. This should populate the cache folder properly.

Steam Freezes

Usually when Steam freezes it will automatically restart itself after a couple of seconds. Otherwise holding the home/Steam/Xbox button for a couple of seconds might get Steam to respond again.

If even that fails, you're have to manually kill the game. If you do not have a keyboard connected to your system the easiest way to do this if to press the power button on the system, wait for the system to fully shut down and turn it back on again.

If you do have a keyboard connected, you can press the key combination Ctrl+Alt+F4 to switch to a terminal. Log in with the username desktop, after which you can use the following command to force Steam to restart:

sudo pkill steam

This will force Steam to restart.

Steam Doesn't Launch

If Steam fails to start or you're stuck on the repairing SteamOS screen and it doesn't fix anything, your best option might be to restore SteamOS from the backup which is made during installation. This will undo any modifications you have made to SteamOS itself, but it will preserve your installed games and your savegames.

To restore SteamOS you'll have to get into the boot menu by spamming either the start button on the Steam controller or the Esc button on your keyboard just after powering it on. Once in the boot menu select the "Restore System Partition" option. The restore process can take a while to finish depending on the speed of your disk, after it is complete the system will automatically reboot back into SteamOS.

Also see: Restoring SteamOS over at the SteamOS support page

Game Issues

Game Freezes

If an application has frozen, you can often still open the Steam Overlay by pressing the home/Steam/Xbox button on your controller. Alternatively, if this doesn't work, hold it for a couple of seconds to get asked if you want to close the game.

If even that fails, you're have to manually kill the game. If you do not have a keyboard connected to your system the easiest way to do this if to press the power button on the system, wait for the system to fully shut down and turn it back on again.

If you do have a keyboard connected, you can press the key combination Ctrl+Alt+F4 to switch to a terminal. Log in with the username desktop, after which you can use the following command to force Steam to restart:

sudo pkill steam

This will both kill the game and force Steam to restart.

Game Doesn't Launch

Unfortunately there are currently games in SteamOS which do not launch. This can be because of various causes and can sometimes be hard to troubleshoot. Some games will give you a clear error message, while other don't seems to do anything. In most cases only the developer is able to fix this problem. Reporting the issue to the game's gamehub usually gets the attention of the developer.

When you report this to a developer, you will want to include any error messages you got and a log of what the Steam client does when you try to launch the game. You can get this log by going into desktop mode, opening a terminal and starting the following command:

tail -f /tmp/dumps/steam_stdout.txt | tee $HOME/log.txt

After which you return to Steam, try to launch the game again, fail and go back to desktop mode. When in desktop mode again, press ctrl+c to stop following the Steam log. Paste the contents of log.txt to a paste site, such as GitHub Gist, or slexy. You will want to add this to the discussion thread on the game's hub with your relevant info and reproducible steps.

If you choose to only paste a snippet on a forum, you will want to use [code] blocks on Steam Community forums, or the correct formatting the game forums use.

[code]
blah blah blah
[/code]

Hardware Issues

Below are some issues that folks may run into on their own hardware when using SteamOS.

Closing laptop lid, causes SteamOS to suspend / sleep

Edit /etc/systemd/logind.conf and make sure you have the below set in the unit file:

HandleLidSwitch=ignore

Restart SteamOS to apply these changes.

Table of Contents generated with DocToc

Table of Contents

SteamOS

Hardware

Documentation Portal

Valve Resources

Community

Clone this wiki locally