Troubleshooting
Table of Contents generated with DocToc
- About
- Owners of Steam Machines
- What to do if you cannot start SteamOS
- General SteamOS Issues
-
Also check the contents of
- I saw an announcement for an OS update, why don't I have it?
- The "Restart to update SteamOS" flag won't go away!
- Gnome-terminal does not launch on SteamOS Brewmaster!
- SteamOS Doesn't Use The Best Resolution Or Refresh Rate For My Display
- Switching to desktop mode leaves monitor/TV with no signal
- The steamos-autorepair process
- The date / time is not right
- Steam Issues
- Game Issues
- Hardware Issues
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.
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.
If SteamOS fails to fully start, or enter the default Big Picture Mode home screen, you may have more serious problems going on. Before continuing below, you will have to boot into recovery mode. To do this, git the ESC key several times as you start your machine. You will reach a GRUB boot menu.
Choose "Advanced options for SteamOS GNU/Linux", which you'll want the first available recovery mode listing near the top. Usually this is the 2nd option after that selection. After some time, the boot process will land you at a root prompt. NOTE: Any commands you enter, should not have the sudo prefix. Please exercise caution.
You will likely need a working network connection:
# List network devices
ifconfig
# Example, call DHCP to get an IP address on eth0 (wired connection)
dhclient eth0
At times, a bad update, or incorrectly applied Steam update can really bring things to a halt. Most recently (as of time of writing), the update did not go smoothly, and users were left without a key folder, /home/steam/.local/share/Steam/tenfoot. This folder is required to launch Big Picture Mode. So what do you do? You have 2 main options:
Run steam via a "fake X server" utility
The below command should allow Steam to update from the CLI / SSH. You will need the program xvfb, which is in the SteamOS repository. An example log of the below actions can be found here. After some time of pulling down files, you should get a "Continuing" message. SteamOS BPM should just automatically start. If it does not, wait 5 or so minutes and perform sudo reboot. If BPM starts by itself, let your system sit for 5-10 minutes. Chances are, /usr/bin/steamos-autorepair.sh will reboot when it has finished it's part.
# Ensure we have a network connection first
ping www.google.com
# Run fix
apt-get install -y xvfb
su - steam -c '/usr/bin/xvfb-run -a -e /tmp/steam_update_log.txt /usr/bin/steam'
Temporarily disabling Auto-login and updating Steam manually
Ensure you have the desktop and steam logins set. Follow the Change The Default Login To The Desktop Session wiki page to boot into desktop mode directly.
Once you login to the desktop (preferably as user "steam"). Start 'steam' from a terminal window. If you login as user "desktop", you should be able to run sudo -u steam -c '/usr/bin/steam' from a terminal window.
If any of the below steps or logs proves too much, or the system is still unusable, you can also consider re-installing SteamOS. This should be considered a last step, unless you do not mind loosing any data. Not all games with Steam Cloud service store game saves /configurations (though, most do). You can retain the /home partition that stores user information by choosing the "Expert Install" of the installation process.
See the Common Installation Issues wiki page.
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 /usr/bin/steamos-update for more.
Review the output from these commands
apt-get -s installapt-get -s updateapt-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
/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.
SteamOS update levels depend on 2 things roughly:
- If you have
steamos-beta-repoinstalled or not (optional) - The current version of
steamos-updatelvel
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
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:
- Remove the offending package, if removal is non-destructive to system packages (use your best judgement here).
- Run
sudo apt-get update sudo reboot- 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
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
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.
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.
A full explanation of the steamos-autorepair script can be found at the SteamOS auto-repair process wiki page.
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
- Open the Activities overview and start typing Date & Time.
- Click on Date & Time to open the panel.
- 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.
- 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.
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.
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.
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.
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
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.
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]
Below are some issues that folks may run into on their own hardware when using SteamOS.
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.
