• Troubleshooting

What you should see on startup

• When Compiz Fusion starts with Compiz Fusion Icon, you should see the window decorator (for example, the window titles), and be able to move the window around.

• When Compiz Fusion starts by itself (with compiz --replace ccp for example), you may not see a decorator, but you should be able to move the windows around by alt-dragging them. You will notice that they are "wobbly".

• If you start Compiz by itself without a configuration backend, you will not be able to move or resize windows. To check if 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 a configuration plugin like gconf, kconfig, ini or ccp. 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 have window titles, and can't move them around by alt-dragging, you most likely could not start Compiz Fusion. Check out below.

Checking for problems

• Check the terminal output of running:

  compiz --replace ccp && emerald --replace &

• Look for errors and then search for them on the Compiz Fusion Forums. You may see

  Wnck-WARNING **: Unhandled action type (nil)

  reappearing many times. This error is non-fatal and does not prevent normal functioning of Emerald or Compiz Fusion.

• 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 drivers. The open source drivers for NVIDIA do not support video acceleration well enough to run Compiz Fusion.

If you're experiencing performance sluggishness, try starting Compiz Fusion with --loose-binding option. With loose binding textures are enabled when created, and the Nvidia driver seems a bit slow when binding textures, that's why this option gives a heavy performance increase on Nvidia.

• For nvidia drivers older than the 100.xx.xx drivers, To fix your beryl/compiz window decorations (titlebars) with an nVidia graphics card, run;

sudo nvidia-xconfig --add-argb-glx-visuals -d 24

• 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 cards and the Xpress 200(M) must use the proprietary fglrx driver with Xgl

Intel GMA Cards

• If you are using an Intel GMA card with AIGLX, you will need to start Compiz Fusion with LIBGL_ALWAYS_INDIRECT=1 prepended.

Apple iBooks

• If you are using a new world iBook with a Radeon video card please refer to:

• http://wiki.compiz-fusion.org/ATI_with_AIGLX

Common problems

Black Window Bug

• Black windows are caused by a bug/limitation in NVIDIA's GLX_EXT_texture_from_pixmap implementation. Turning off the blur effect may delay the appearance of the bug. Running compiz with '--indirect-rendering' should almost completely eliminate black windows, although it breaks vsync. The black window bug should be 99% fixed in the newest version of the NVIDIA Graphics Driver for Linux, 100.14.19. Please upgrade to this driver as it features better memory management in this case. You will almost certainly not experience the problem with Direct Rendering, however you still can get a black screen if you switcher Virtual Console repeatedly.

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 proprietary NVIDIA driver is not enabled (and operational).

  A white screen, (shown by the symptoms of a completely white screen, but all desktop effects work (You can rotate the cube with <Ctrl><Alt>F1) means that there is a bug in 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 drivers, 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: rm ~/.kde/share/config/ksmserverrc.

  It seems that the bug is created by an entry in ksmserverrc reading something like:

  • program1=

    restartCommand1=compiz,--replace,gconf,decoration,...