How to debug Xorg problems

Foreword

If you are experiencing a problem with Xorg, please see the common bugs document before filing a bug. Some easy configuration tweaks that fix a wide range of issues are listed there. If the problem you are seeing is not listed there or none of the workarounds seem to help, please consider filing a bug to help us make Fedora run better on your hardware.

Be prepared to include some information (logs) about your system as well. These should be complete (no snippets please), not in an archive, uncompressed, with MIME type set as text/plain.

Identifying your problem area

What driver am I using?

If you do not know already, try to find out what video driver you are using. Examine the file /var/log/Xorg.0.log. Quite early on, you will see some lines like this:

(II) VESA(0): initializing int10
(II) VESA(0): Bad V_BIOS checksum

The word in capital letters after (II) is the name of the driver in use (so, in this case, the word is VESA, indicating the vesa driver is in use). Drivers are packaged with the name xorg-x11-drv-(name), so the vesa driver is in the package xorg-x11-drv-vesa.

If you are using a driver with the name nvidia (not nv or nouveau) or fglrx, you are using a proprietary third-party video driver (respectively, the proprietary drivers provided by NVIDIA and AMD/ATI). Please do not report any bugs in these drivers to Fedora, as we do not provide or support these drivers. Report bugs either to the place where you got these drivers, or to NVIDIA or AMD.

What area might the problem be in?

• If the problem in question occurs when using 3D-accelerated applications - for instance, Blender, or 3D-accelerated games - the problem is a 3D acceleration issue, and you should include the information outlined in the appropriate section further down this page.

• Several drivers in Fedora use kernel mode setting (whereby the detection and selection of the output resolution and refresh rate is done in the kernel rather than the video card driver) by default. Some of those can also function without kernel mode setting. As of Fedora 12, these drivers are intel, radeon and nouveau. In Fedora 13 only radeon supports both modes of operation. If you are using one of these drivers, test if the problem is related to kernel mode setting by disabling it: boot with the parameter nomodeset added to the kernel command line. If this affects the problem, it is a KMS-related issue, and you should include the information outlined in the appropriate section further down this page.

Information to include in your report

All bug reports

In all cases, the following should be attached to your bug report:

• All of the X server log file(s): /var/log/Xorg.*.log
• Your smolt profile. You can dump it to /tmp/smoltprofile.txt with the following command: smoltSendProfile -p > /tmp/smoltprofile.txt
• If you use a xorg.conf, please include it in the bug report, otherwise, please specify in the bug report that it does not exist. Usually this would be located at /etc/X11/xorg.conf, but see the xorg.conf manpage - man xorg.conf - for other standard locations.
• /var/log/Xorg.0.log from a trial run where you move your xorg.conf aside and let Xorg autodetect your hardware (if you have such a file).
• /var/log/dmesg (please add drm.debug=15 as boot parameter and reboot) especially in case of crashes and using KMS.
• content of /var/log/gdm/ only in cases there is nothing interesting in /var/log/Xorg.*.log and dmesg output

Rendering problems (unreadable text, corrupted display...)

As well as the information from the 'all bug reports' section, include the following information:

• A screenshot showing the problem if at all possible.

KMS-related issues

As well as the information from the 'all bug reports' section, include the following information:

• Boot with the parameter drm.debug=15 added to the kernel command line, reboot and attach /var/log/messages, /var/log/dmesg, and /var/log/Xorg.0.log to your bug report.
• Also, if the driver for your card supports it (currently only radeon), boot with the parameter nomodeset added to the kernel command line and attach /var/log/Xorg.0.log to your bug report.
• Explain how the behaviour differs when KMS is disabled, and whether both cases are problematic (but different), or whether the non-KMS case is what you consider to be the correct behavior.

Intel-specific

• For display setup issues (outputs shaky or not lighting up), collect the video ROM for the chip:

   sudo dd if=/dev/mem of=/tmp/rom bs=64k skip=12 count=1

and a register snapshot from the broken configuration:

   sudo intel_reg_snapshot > /tmp/snapshot

intel_reg_snapshot is in the intel-gpu-tools package. Note that you may need to {filename|ssh}} into the machine in order to collect this information.

3D acceleration issues

As well as the information from the 'all bug reports' section, include the following information:

• Output of the command glxinfo (if this is not installed, install the package glx-utils)
• A screenshot, if possible (if the system has crashed but the display on screen is something other than just blank, take a picture with a digital camera and attach that)
• Information as to whether or not other OpenGL applications are able to run without problems.

Creating a xorg.conf

If you need to make manual changes to X configuration, you will need to create a xorg.conf file if it doesn't already exist.

Debugging problems with Intel graphics adapters

If you are suffering from problems with an Intel graphics adapter such as failure of X to start at all, hangs or freezes or crashes in the graphical environment, display corruption, failure of 3D accelerated applications to work properly or similar problems, and your issue is not specifically covered elsewhere on this page, the following general advice may be of use.

First, make sure you have applied all system updates, in case the problem has already been fixed.

In Fedora 12 and earlier, several such issues may be worked around by disabling kernel mode setting. To do this, add

nomodeset

as a kernel parameter. If this solves your problem, please check whether a bug has already been reported for it, and if not, file a new bug report on the xorg-x11-drv-intel component, explaining your symptoms, and providing all the usual information required for X.org bug reports, as indicated above. In Fedora 13 and later kernel mode setting will be the only available method, and so we wish to ensure all problems caused by kernel mode setting are fixed.

If this does not resolve your issue, one other potential workaround is to change to a different acceleration method. To do this, add a line:

Option "AccelMethod" "EXA"

or:

Option "AccelMethod" "XAA"

to the Device section of /etc/X11/xorg.conf. If that file does not exist, see How_to_create_xorg.conf for instructions on how to create it. Again, if doing this works around the problem you are experiencing, please check whether a bug report on the problem has already been filed, and if not, please file a new bug report on the xorg-x11-drv-intel component, explaining your symptoms, and providing all the usual information required for X.org bug reports as indicated above. These legacy acceleration methods will be removed in future, so any bugs in the new acceleration method (UXA) need to be fixed.

Debugging ATI / AMD graphics adapters

If you are experiencing failure to start the graphical desktop, hanging or freezing, corruption, or slow performance with an ATI / AMD graphics adapter, you may try the following.

First, make sure you have applied all system updates; some known bugs have been fixed.

Some issues may be worked around by disabling kernel mode setting. To do this, add

nomodeset

as a kernel parameter. If this solves your problem, please check whether a bug has already been reported for it, and if not, file a new bug report on the xorg-x11-drv-ati component, explaining your symptoms, and providing all the usual information required for X.org bug reports. In future kernel mode setting will be the only available method, and so we wish to ensure all problems caused by kernel mode setting are fixed.

If this does not resolve your issue, one other potential workaround is to change to a different acceleration method. To do this, add a line:

Option "AccelMethod" "XAA"

to the Device section of /etc/X11/xorg.conf. If that file does not exist, see How_to_create_xorg.conf for instructions on how to create it. Again, if doing this works around the problem you are experiencing, please check whether a bug report on the problem has already been filed, and if not, please file a new bug report on the xorg-x11-drv-ati component, explaining your symptoms, and providing all the usual information required for X.org bug reports, as indicated above. These legacy acceleration methods will be removed in future, so any bugs in the new acceleration method (EXA) need to be fixed.

If this does not resolve your issue, there is another configuration option to try. Add a line:

Option "AccelDFS" "off"

to the Device section of /etc/X11/xorg.conf. If that file does not exist, see How_to_create_xorg.conf for instructions on how to create it. Again, if doing this works around the problem you are experiencing, please check whether a bug report on the problem has already been filed, and if not, please file a new bug report on the xorg-x11-drv-ati component, explaining your symptoms, and providing all the usual information required for X.org bug reports as indicated above.

Finally, if this still does not resolve your issue, try adding this line:

Option "DRI" "off"

to the Device section of /etc/X11/xorg.conf. Again, if doing this works around the problem you are experiencing, please check whether a bug report on the problem has already been filed, and if not, please file a new bug report on the xorg-x11-drv-ati component, explaining your symptoms, and providing all the usual information required for X.org bug reports, as indicated above.

Input devices

Debugging of input devices is covered by a special wiki page.

Stack traces

You will need a stack trace if your X server crashes.

See the documentation on the upstream wiki.