This article describes some common problems you may encounter when starting Compiz, and what you can do about them.
Contents
What you should see on startup
When Compiz starts with Compiz Fusion Icon, you should see window borders and be able to move windows around by dragging the titlebars.
When Compiz Fusion starts by itself (through the compiz --replace ccp command, for example), you may not see any window borders, but you should still be able to move the windows around by holding down the Alt key and dragging them with the left mouse button. You will notice that they are "wobbly".
If you start Compiz by itself without specifying a configuration plugin on the command line, you will not be able to move or resize windows. To check whether Compiz is running, open two windows and see if you can switch between them by clicking on the windows. If you can, that means Compiz is running but no plugins are loaded. You will need to start Compiz with the name of a configuration plugin on the command line, such as ccp, gconf, kconfig, or ini. If this still doesn't work, you may have a plugin ABI version mismatch, and you will need to re-compile your plugins.
- If you don't see window borders, can't move windows around by Alt-dragging, and can't switch between windows, you most likely couldn't start Compiz. See below for potential problems and solutions.
Checking for problems
- Check the terminal output of running the following command:
compiz --replace ccp & emerald --replace &
Look for error messages and then search for them on the Compiz Fusion Forum. You may see
Wnck-WARNING **: Unhandled action type (nil)
andA handler is already registered for the path starting with path[0] = "org"
reappearing many times. These errors are non-fatal and does not prevent normal functioning of Compiz Fusion or Emerald.
If you still can't find the solution, check out #compiz-fusion on the FreeNode IRC network.
Common Mistakes
nVidia Cards
If you have an nVidia card, make sure you are using the proprietary (sometimes referred to as restricted) nvidia driver. The open source nv driver for nVidia does not support 3D acceleration well enough to run Compiz Fusion.
If you're experiencing performance sluggishness, try starting compiz with the --loose-binding option. With loose binding, textures are enabled when created, and the nvidia driver seems a bit slow when binding textures, which is why this option yields a significant performance improvement.
With nvidia drivers earlier than version 100.14.09 drivers, you may not be able to see any window borders. To fix the problem, either run the following command:
sudo nvidia-xconfig --add-argb-glx-visuals -d 24
Or edit the Screen section of your /etc/X11/xorg.conf file to contain the following line:
DefaultDepth 24
And edit the Device section to contain the following line:
Option "AddARGBGLXVisuals" "true"
Then restart X.
ATI Cards
If you are using an ATI card, Compiz Fusion requires at least a Radeon 7000 (or M6). From the 7000 to the X1050, you can use AIGLX with the open source ati driver. All X1xxx series cards and the Xpress 200(M) must use the proprietary fglrx driver. Using driver version >= 8.3 (gentoo 8.4.XXX) is recommended as AIGLX is available as of 8.3. If you decide to use older fglrx drivers, you're stuck with Xgl.
Intel GMA Cards
If you are using an Intel GMA card with AIGLX, you will need to start Compiz with LIBGL_ALWAYS_INDIRECT=1 prepended to the command line and run compiz with the --indirect-rendering option, as with the following example:
LIBGL_ALWAYS_INDIRECT=1 INTEL_BATCH=1 compiz --replace --indirect-rendering --sm-disable ccp &
Apple iBooks
If you are using a new world iBook with a Radeon video card, please refer to the article about using ATI with AIGLX.
Common Problems
No Window Borders
When you start Compiz, your window borders disappear and you can no longer see each window's title, or minimize/maximize/close buttons. There are many potential causes for this very common problem, and is usually indicative of a Compiz or X server misconfiguration, or a misunderstanding of how Compiz is supposed to work.
Is a Window Decorator Running?
Check whether a window decorator is running. Enter the following command into a console window to find out:
ps ax | egrep '(decorator|emerald)'
If you don't see any commands starting with "emerald", "gtk-window-decorator", or "kde-window-decorator", then no window decorator is running. Try starting Emerald with the following command:
emerald --replace
Is the Window Decoration Plugin Enabled?
Check whether the Window Decoration plugin is enabled. It must be enabled for the borders drawn by window decorators to become visible. Run ccsm, then ensure that the check box next to "Window Decoration" is marked.
Is Compiz Running?
There may be a problem with the way Compiz is being started. Enter this command into a console window to find out how and whether Compiz is running:
ps ax | grep compiz
If you don't see a command starting with "compiz" or "compiz.real" in the output, then Compiz is failing to start altogether. Please refer to the Common Mistakes section above to see whether anything describes your situation. Also check the Setup article to see whether your X server was properly configured.
If you do see a "compiz" or "compiz.real" command in the output, check whether "ccp" is part of the command line. The ccp plugin is required for Compiz to interact with settings made in ccsm. If it's missing from your Compiz command line, you should edit your startup process to include ccp in Compiz's command line, as in this example:
compiz --replace ccp
Using an nVidia Card?
As described in the Common Mistakes section, you may need to make some adjustments to your /etc/X11/xorg.conf file in order to see window borders even if everything else is working perfectly.
Black Window Bug
Black windows are caused by a bug/limitation in nVidia's implementation of GLX_EXT_texture_from_pixmap. Turning off the blur effect may delay the appearance of the bug. Running compiz with the --indirect-rendering option should almost completely eliminate black windows, although syncing to VBlank won't work with indirect rendering.
The black window bug should have been mostly fixed as of version 100.14.19 of the nvidia driver. Using that or a later version of the driver, you will almost certainly not experience the problem with direct rendering, though you may still see a black screen if you repeatedly switch to and from virtual consoles.
White Screen
A white screen can be a symptom of different problems depending on your video card. For nVidia cards, it usually means that the nvidia driver is not enabled or operational.
This problem is characterised by a completely white screen where desktop effects (such as rotating the cube with <Ctrl><Alt>Left or <Ctrl><Alt>Left) continue to work, but no window contents are visible. It means that there is a bug with binding pixmaps to textures. This usually means that for whatever rendering method you are using, the GLX_EXT_texture_from_pixmap extension is broken. Please upgrade your driver, X server, and/or Xgl if you are using it.
"White cube of Death" on KDE
When using Compiz with KDE and a NVIDIA card, you may encounter the "White Cube of Death" problem. When starting KDE, for a short time you can see your desktop, then everything turns white. You are still able to move the mouse (the mouse pointer changes over icons) and rotate the cube, but all cube faces are white.
A workaround is to log in with a different session (e.g. Window Maker or FVWM) which does not use Compiz, then start kcontrol, go to KDE Components -> Session Manager and select "Start with an empty session". Now Compiz should work without problems. If you cannot log in and start kcontrol, log in at a text console and remove the KDE Session configuration file with the following command:
rm ~/.kde/share/config/ksmserverrc
It seems that the bug is created by an entry in ~/.kde/share/config/ksmserverrc reading something like:
program1= restartCommand1=compiz,--replace,gconf,decoration
Windows Don't Update
When using the intel or ati driver with AIGLX, you may notice that all your windows seem to be frozen even as you interact with them. Nothing in any window updates until you rotate the cube or otherwise switch viewports.
Adding the following line to the Device section of your /etc/X11/xorg.conf file should fix the problem:
Option "XAANoOffscreenPixmaps" "true"
What to do if compiz crashes
In order to be able to track down crash reasons, the developers mainly need two things:
- A meaningful description of steps how to reproduce the crash.
- A backtrace of the crash with debug symbols together with information about the used compiz version.
A backtrace of a compiz crash can be created using the crash handler plugin which is part of the plugins-extra package. After enabling that plugin, a crash trace with the name compiz_crash-<pid>.out is written everytime compiz crashes to a directory specifiable in the crashhandler plugin options (by default: /tmp). That dump alone is not very helpful, though, because it doesn't contain source code references. In order to get them, debug information needs to be installed. How to do that depends on your distribution:
In Fedora, issue the command debuginfo-install compiz compiz-fusion compiz-fusion-extras
For Ubuntu, the procedure is described in the Ubuntu wiki. You need the -dbgsym packages for compiz, compiz-fusion-plugins-main and compiz-fusion-plugins-extra.
As soon as you have a backtrace with debug information, submit them either to the forums or to the bug tracker.