Chapter 8. Common Problems

This section provides solutions to common problems associated with the NVIDIA FreeBSD x86_64 Driver.

My X server fails to start, and my X log file contains the error:

(EE) NVIDIA(0): The NVIDIA kernel module does not appear to
(EE) NVIDIA(0):      be receiving interrupts generated by the NVIDIA graphics
(EE) NVIDIA(0):      device PCI:x:x:x. Please see the COMMON PROBLEMS
(EE) NVIDIA(0):      section in the README for additional information.

This can be caused by a variety of problems, such as PCI IRQ routing errors, I/O APIC problems, conflicts with other devices sharing the IRQ (or their drivers), or MSI compatibility problems.

If possible, configure your system such that your graphics card does not share its IRQ with other devices (try moving the graphics card to another slot if applicable, unload/disable the driver(s) for the device(s) sharing the card's IRQ, or remove/disable the device(s)).

X starts for me, but OpenGL applications terminate immediately.

If X starts but you have trouble with OpenGL, you most likely have a problem with other libraries in the way, or there are stale symlinks. See Chapter 4, Installed Components for details.

You should also check that the correct extensions are present;

    % xdpyinfo

should show the “GLX” and “NV-GLX” extensions present. If these two extensions are not present, then there is most likely a problem loading the glx module, or it is unable to implicitly load GLcore. Check your X config file and make sure that you are loading glx (see Chapter 6, Configuring X for the NVIDIA Driver). If your X config file is correct, then check the X log file for warnings/errors pertaining to GLX. Also check that all of the necessary symlinks are in place (refer to Chapter 4, Installed Components).

When Xinerama is enabled, my stereo glasses are shuttering only when the stereo application is displayed on one specific X screen. When the application is displayed on the other X screens, the stereo glasses stop shuttering.

This problem occurs with DDC and "blue line" stereo glasses, that get the stereo signal from one video port of the graphics card. When a X screen does not display any stereo drawable the stereo signal is disabled on the associated video port.

Forcing stereo flipping allows the stereo glasses to shutter continuously. This can be done by enabling the OpenGL control "Force Stereo Flipping" in nvidia-settings, or by setting the X configuration option "ForceStereoFlipping" to "1".

Stereo is not in sync across multiple displays.

There are two cases where this may occur. If the displays are attached to the same GPU, and one of them is out of sync with the stereo glasses, you will need to reconfigure your monitors to drive identical mode timings; see Chapter 16, Programming Modes for details.

If the displays are attached to different GPUs, the only way to synchronize stereo across the displays is with a Quadro Sync device, which is only supported by certain NVIDIA RTX/Quadro cards. See Chapter 24, Configuring Frame Lock and Genlock for details.

X fails to start, and during boot up time I get error messages

nvidia0: NVRM: NVIDIA REG resource alloc failed.

or

nvidia0: NVRM: NVIDIA IRQ resource alloc failed.

The system BIOS has not properly set up your graphics card; FreeBSD can't currently set up PCI devices that the BIOS leaves unconfigured. Uncheck "PNP-OS" in your system BIOS.

X fails to start, and during boot up time I get the following error message:

nvidia0: NVRM: NVIDIA MEM resource alloc failed.

On certain FreeBSD kernels, it may be necessary to add the following line to /boot/loader.conf:

hw.pci.allow_unsupported_io_range="1"

This should allow the NVIDIA kernel module to attach.

My X server fails to start, and my X log file contains the error:

(EE) NVIDIA(0): Failed to initialize the NVIDIA kernel module!

Nothing will work if the NVIDIA kernel module does not function properly. If you see anything in the X log file like

(EE) NVIDIA(0): Failed to initialize the NVIDIA kernel module!

then there is most likely a problem with the NVIDIA kernel module.

The NVIDIA kernel module may print error messages indicating a problem -- to view these messages check the output of dmesg, /var/log/messages, or wherever syslog is directed to place kernel messages. These messages are prepended with "NVRM".

When I attempt to start `nvidia-settings`, I get an error message of the form:

 Shared object "libgtk-x11-2.0.so.0" not found, required by nvidia-settings

Due to differences between the gtk+-2.x ports packages included with different FreeBSD releases, the prebuilt nvidia-settings binary shipped with the NVIDIA driver may not work with FreeBSD releases more recent than FreeBSD 10.4.

If you have a recent ports package of gtk+-2.x and gmake installed on your system, you can build the nvidia-installer utility from source to solve this problem.

Download nvidia-settings-460.84.tar.bz2 from https://download.nvidia.com/XFree86/nvidia-settings You can then extract, build and install it (to /usr/local/bin) with:

    % gmake install

When I attempt to run `nvidia-xconfig` after the NVIDIA FreeBSD graphics driver installation, I get an error message of the form:

nvidia-xconfig: Command not found.

Depending on the shell you are using, you may need to force it to recompute its internal table of executable files present in the directories listed in the $PATH variable. Assuming you are using the FreeBSD default shell you can do so by issuing the command:

    % rehash

OpenGL applications are running slowly

The application is probably using a different library that still remains on your system, rather than the NVIDIA supplied OpenGL library. See Chapter 4, Installed Components for details.

Fonts are incorrectly sized after installing the NVIDIA driver.

Incorrectly sized fonts are generally caused by incorrect DPI (Dots Per Inch) information. You can check what X thinks the physical size of your monitor is, by running:

 % xdpyinfo | grep dimensions

This will report the size in pixels, and in millimeters.

If these numbers are wrong, you can correct them by modifying the X server's DPI setting. See Appendix E, Dots Per Inch for details.

OpenGL applications don't work, and my X log file contains the error:

(EE) NVIDIA(0): Unable to map device node /dev/zero with read and write
(EE) NVIDIA(0):     privileges.  The GLX extension will be disabled on this 
(EE) NVIDIA(0):     X screen.  Please see the COMMON PROBLEMS section in the 
(EE) NVIDIA(0):     README for more information.

The NVIDIA OpenGL driver must be able to map anonymous memory with read and write execute privileges in order to function correctly. The driver needs this ability to allocate aligned memory, which is used for certain optimizations. Currently, GLX cannot run without these optimizations.

My log file contains a message like the following:

(WW) NVIDIA(GPU-0): Unable to enter interactive mode, because non-interactive
(WW) NVIDIA(GPU-0): mode has been previously requested.  The most common
(WW) NVIDIA(GPU-0): cause is that a GPU compute application is currently
(WW) NVIDIA(GPU-0): running. Please see the README for details.

This indicates that the X driver was not able to put the GPU in interactive mode, because another program has requested non-interactive mode. The GPU watchdog will not run, and long-running GPU compute programs may cause the X server and OpenGL programs to hang. If you intend to run long-running GPU compute programs, set the Interactive option to "off" to disable interactive mode.

I see a blank screen or an error message instead of a login screen or desktop session

Installation or configuration problems may prevent the X server, a login/session manager, or a desktop environment from starting correctly. If your system is failing to display a login screen, or failing to start a desktop session, try the following troubleshooting steps:

  • Make sure that you are using the correct X driver for your configuration. Recent X servers will be able to automatically select the correct X driver in many cases, but if your X server does not automatically select the correct driver, you may need to manually configure it. For example, systems with multiple GPUs will likely require a PCI BusID in the "Device" section of the X configuration file, in order to specify which GPU is to be used.

    If you are planning to use NVIDIA GPUs for graphics, you can run the nvidia-xconfig utility to automatically generate a simple X configuration file that uses the NVIDIA X driver. If you are not using NVIDIA GPUs for graphics (e.g. on a server system where displays are driven by an onboard graphics controller, and NVIDIA GPUs are used for non-graphical computational purposes only), do not run nvidia-xconfig.

  • Some recent desktop environments (e.g. GNOME 3, Unity), window managers (e.g. mutter, compiz), and session managers (e.g. gdm3) require a working OpenGL driver in order to function correctly. In addition to making sure that the X server is configured to use the correct X driver for your configuration, please ensure that you are using the correct OpenGL driver to match your X driver.

  • Some desktop environments (e.g. GNOME 3, Unity) and window managers (e.g. mutter) do not properly support multiple X screens, leaving you with a blank screen displaying only a cursor on the non-primary X screen. If you encounter such a problem, try configuring X with a single X screen, or switching to a different desktop environment or window manager.

  • Desktop environments, window managers, and session managers that require OpenGL typically also require the X Composite extension. If you have disabled the Composite extension, either explicitly, or by enabling a feature that is not compatible with it, try re-enabling the extension (possibly by disabling any incompatible features). If you are unable to satisfy your desired use case with the Composite extension enabled, try switching to a different desktop environment, window manager, and/or session manager that does not require Composite.

  • Check the X log (e.g. /var/log/Xorg.0.log) for additional errors not covered above. Warning or error messages in the log may highlight a specific problem that can be fixed with a configuration adjustment.

The display settings I configured in nvidia-settings do not persist.

Depending on the type of configuration being performed, nvidia-settings will save configuration changes to one of several places:

  • Static X server configuration changes are saved to the X configuration file (e.g. /etc/X11/xorg.conf). These settings are loaded by the X server when it starts, and cannot be changed without restarting X.

  • Dynamic, user-specific configuration changes are saved to ~/.nvidia-settings-rc. nvidia-settings loads this file and applies any settings contained within. These settings can be changed without restarting the X server, and can typically be configured through the nvidia-settings command line interface as well, or via the RandR and/or NV-CONTROL APIs.

  • User-specific application profiles edited in nvidia-settings are saved to ~/.nv/nvidia-application-profiles-rc. This file is loaded along with the other files in the application profile search path by the NVIDIA OpenGL driver when it is loaded by an OpenGL application. The driver evaluates the application profiles to determine which settings apply to the application. Changes made to this configuration file while an application is already running will be applied when the application is next restarted. See Appendix H, Application Profiles for more information about application profiles.

Settings in ~/.nvidia-settings-rc only take effect when processed by nvidia-settings, and therefore will not be loaded by default when starting a new X session. To load settings from ~/.nvidia-settings-rc without actually opening the nvidia-settings control panel, use the --load-config-only option on the nvidia-settings command line. nvidia-settings --load-config-only can be added to your login scripts to ensure that your settings are restored when starting a new desktop session.

Even after nvidia-settings has been run to restore any settings set in ~/.nvidia-settings-rc, some desktop environments (e.g. GNOME, KDE, Unity, Xfce) include advanced display configuration tools that may override settings that were configured via nvidia-settings. These tools may attempt to restore their own display configuration when starting a new desktop session, or when events such as display hotplugs, resolution changes, or VT switches occur.

These tools may also override some types of settings that are stored in and loaded from the X configuration file, such as any MetaMode strings that may specify the initial display layouts of NVIDIA X screens. Although the configuration of the initial MetaMode is static, it is possible to dynamically switch to a different MetaMode after X has started. This can have the effect of making the set of active displays, their resolutions, and layout positions as configured in the nvidia-settings control panel appear to be ineffective, when in reality, this configuration was active when starting X and then overridden later by the desktop environment.

If you believe that your desktop environment is overriding settings that you configured in nvidia-settings, some possible solutions are:

  • Use the display configuration tools provided as part of the desktop environment (e.g. gnome-control-center display, gnome-display-properties, kcmshell4 display, unity-control-center display, xfce4-display-settings) to configure your displays, instead of the nvidia-settings control panel or the xrandr command line tool. Setting your desired configuration using the desktop environment's tools should cause that configuration to be the one which is restored when the desktop environment overrides the existing configuration from nvidia-settings. If you are not sure which tools your desktop environment uses for display configuration, you may be able to discover them by navigating any available system menus for "Display" or "Monitor" control panels.

  • For settings loaded from ~/.nvidia-settings-rc which have been overridden, run nvidia-settings --load-config-only as needed to reload the settings from ~/.nvidia-settings-rc.

  • Disable any features your desktop environment may have for managing displays. (Note: this may disable other features, such as display configuration tools that are integrated into the desktop.)

  • Use a different desktop environment which does not actively manage display configuration, or do not use any desktop environment at all.

Some systems may have multiple different display configuration utilities, each with its own way of managing settings. In addition to conflicting with nvidia-settings, such tools may conflict with each other. If your system uses more than one tool for configuring displays, make sure to check the configuration of each tool when attempting to determine the source of any unexpected display settings.

My displays are reconfigured in unexpected ways when I plug in or unplug a display, or power a display off and then power it on again.

This is a special case of the issues described in “The display settings I configured in nvidia-settings do not persist.”. Some desktop environments which include advanced display configuration tools will automatically configure the display layout in response to detected configuration changes. For example, when a new display is plugged in, such a desktop environment may attempt to restore the previous layout that was used with the set of currently connected displays, or may configure a default layout based upon its own policy.

On X servers with support for RandR 1.2 or later, the NVIDIA X driver reports display hotplug events to the X server via RandR when displays are connected and disconnected. These hotplug events may trigger a desktop environment with advanced display management capabilities to change the display configuration. These changes may affect settings such as the set of active displays, their resolutions and positioning relative to each other, per-display color correction settings, and more.

In addition to hotplug events generated by connecting or disconnecting displays, DisplayPort displays will generate a hot unplug event when they power off, and a hotplug event when they power on, even if no physical plugging in or unplugging takes place. This can lead to hotplug-induced display configuration changes without any actual hotplug action taking place.

Upon suspend, the NVIDIA X driver will incur an implicit VT switch. If a DisplayPort monitor is powered off when a VT switch or modeset occurs, RandR will forget the configuration of that monitor. As a result, the display will be left without a mode once powered back on. In the absence of an RandR-aware window manager, bringing back the display will require manually configuring it with RandR.

If display hotplug events are resulting in undesired configuration changes, try the solutions and workarounds listed in “The display settings I configured in nvidia-settings do not persist.”. Another workaround would be to disable the NVIDIA X driver's reporting of hotplug events with the UseHotplugEvents X configuration option. Note that this option will have no effect on DisplayPort devices, which must report all hotplug events to ensure proper functionality.

My remote desktop software doesn't work when no displays are attached.

Some desktop environments or window managers might not function correctly if no displays are exposed via the RandR API. When the NVIDIA X driver is configured for headless operation, either with 'Option "AllowEmptyInitialConfiguration"' and no connected displays, with 'Option "MetaModes" "NULL"', or with 'Option "UseDisplayDevice" "none"', it will not expose any displays via RandR.

To work around software that requires RandR displays on a machine that is only intended to be used remotely, you can connect a physical display, or configure the X driver to behave as if a physical display were connected using the "ConnectedMonitor" option. See Appendix B, X Config Options for additional information about the "ConnectedMonitor" option.