Troubleshooting on Unix/Linux

Installation difficulties

If the installation fails and for late-breaking news, check the FAQ for your platform at support.wolfram.com/mathematica/systems as well as The Network Mathematica System Administrator's Guide.

If you need to contact Technical Support about installation, be sure to have your license number and a copy of the installation manifest, located in the Mathematica directory in SystemFiles/Installation/SystemResources/Manifests.

Preferences

There are three directories in ~/.Mathematica that store your preferences: FrontEnd, Kernel, and Licensing. The most convenient way to reset the front end to the default values is by using the command

mathematica -cleanStart

This will remove all the caches located in the FrontEnd directory and rebuild them automatically.

A corrupt preference file cache may cause the following problems: the front end may produce an error or quit immediately on startup; the Help Browser may not open; or the list of menus may be corrupted. If any of these occurs, you should reset the front end using the cleanStart option.

If the front end initialization file becomes corrupted: the listing of files in the File menu may be incorrect; the Find command may not work; the listing of palettes may be incorrect; or the front end may quit immediately on startup. If any of these things happens, remove the init.m file in the FrontEnd directory. Please send the corrupted init.m file to Technical Support for diagnostic purposes. Deleting the init.m file will cause Mathematica to revert to its default settings. Restart the front end. The init.m file will also be rebuilt automatically.

Help files

If Mathematica is unable to locate information in the Help Browser, make sure that the documentation has been installed. By default, a minimal installation will not load help files.

Graphics

Caches are created for graphics to allow for quick retrieval of images. If you change the display settings for your monitor, graphics in your notebook may appear strange. To rerender all graphics after changing any setting to your monitor, select the graphics and use Cell Rerender Graphics.

If the front end is using a private colormap, the screen will flicker as you move your mouse from the front end to other applications. This is normal.

Standard add-on packages

If you are unable to load any standard add-on packages, make sure that the packages have been installed. Make sure a backquote is used in the loading command, as in

<< Graphics'Graphics3D'

Crashes

If the front end crashes, the kernel may be left running in the background. To stop the kernel:

1. Find the process ID of the kernel:

% ps -c

2. Using that process ID, issue a kill command.

% kill pid

Keyboard settings

If you are having trouble with the Mod1 or Mod2 key, go to Help X Environment Information to find out which keys represent Mod1 and Mod2 and to reset the key assignment.

Note: To change Mod1 and Mod2 keys, you need to use the xmodmap command.

Fonts

If you see the error message xset:bad font path element, check to see if the fonts included with Mathematica are on the font path for the server and are accessible. See man xset for more details on how to set up your font path.

Display errors

If you see the error message XMathematica: can't open display, you need to make sure that you have the DISPLAY environment variable set correctly.

If you are running the front end remotely, you must give permission to the remote machine to display to your monitor. See Running the Kernel for step-by-step instructions on how to run a front end remotely.

Window managers

Some window managers use keyboard shortcuts for special commands that conflict with Mathematica's menu shortcuts. An example of this is fvwm and . If this occurs, you must access the menu command with the pointer.

Other window managers bind keysyms when holding down the Mod1 or Mod2 key and another key. In order for some front end keybindings to work correctly, the front end option -pureKeys may need to be set (see below).

In some window managers, NumLock turns the cursor into a hand when over the window. When you click in the window, all you can do is drag the window.

Mathematica is a very complex program that makes sophisticated use of standards-conforming window managers. For this reason, use of pre-release versions of window managers may cause problems.

Front end resources

The standard X resources that control colors, fonts, sizes, and so on are supported by the X front end. For a list of such resources, see the X Window System User's Guide from O'Reilly & Associates.

The X front end also has the following specialized resources:

*applicationDepth. This sets the color depth for the front end.

*background. Sets the menu and dialog background colors (a standard X toolkit option).

*backgroundTaskDelay. Typically set to 200 milliseconds, this is the time the front end will wait for background events (such as typing) until doing tasks like PostScript rendering. When running the front end over a network, this number may need to be increased to a figure such as 300 or 400.

*cleanStart. If specified, this tells the front end to ignore caches stored in the user's home directory.

*Menu*fontlist. Sets the fonts to be used in the menus.

*mod1KeySym. Specify which key will represent Mod1.

*mod2KeySym. Specify which key will represent Mod2.

*preferencesDirectory. Specify the location where preferences are stored. By default this is set to ~/.Mathematica.

*printCommand. Give the command that will send the file to the printer, such as lpr or lp. This command will appear in the Print dialog box.

*pureKeys. When set to True, the front end prevents manufacturer keycodes from being modified by anything except the key. For example, some systems may have 6 mapped to the onequarter keysym, and this will not work with the X front end.

*singleLaunch. This resource takes values True, False, and Query. It allows only one copy of the front end to exist per DISPLAY setting if set to True, and allows multiple front ends to run if set to False. Setting this resource to Query will cause the front end to ask if you wish to have each file opened by a separate front end.

*standardColormap. This defines what colormap should be used.

*tileWidth. If lines appear in dithered graphics, try setting this to 8 or 16.

*usePrivateColormap. If set to True, this will cause a private colormap to be established.

*useStandardColormaps. This gives control over colormaps. If this is set to True, then the front end will use a standard colormap if available. If the *standardColormap resource is set, it will try to use that one first. Otherwise, for color visuals it searches for (in order): RGB_DEFAULT_MAP, RGB_BEST_MAP, and RGB_GRAY_MAP. For grayscale visuals it searches for (in order): RGB_GRAY_MAP and RGB_DEFAULT_MAP.

*visualClass. This should be set to one of the following: PseudoColor, TrueColor, DirectColor, StaticColor, StaticGray, or GrayScale.

*visualID. This allows the selection of a specific visualID on a DISPLAY connection.

Front end command-line options

-appHelper. Combines the options -querySingleLaunch and -forceSaveAs. This option is typically used when configuring Mathematica as a helper application for web browsers.

-backgroundTaskDelay. Specifies the time the front end delays background tasks like PostScript rendering when waiting for input. The delay is measured in milliseconds and the default setting is 100.

-best. Asks the front end to use an optimal visual, depth, and colormap combination.

-cleanStart. Tells the front end to ignore caches stored in the user's preferences directory, $UserAddOnsDirectory/FrontEnd/Caches, and rebuilds the front end global preferences storage file, $UserAddOnsDirectory/FrontEnd/init.m. This option can also be abbreviated as -clean.

-copyright. Tells the front end to display copyright information from the command line.

-font. Specifies the font that the front end uses in menus, buttons, and so on. The X program xfontsel can be used to obtain a fontname. The font name may be expressed as either an X Logical Font Description or as a valid font alias.

-forceSaveAs. Forces the front end to bring up the Save dialog box when closing a file passed to it on the command line. This option is typically used when configuring Mathematica as a helper application for web browsers.

-help. Prints a listing of all available command-line options.

-lmverbose. Prints diagnostic information to stderr on connecting to the license manager. This is useful for diagnosing problems related to the license server.

-mathlink. Causes the front end to run in MathLink mode. In MathLink mode, the front end runs as a child process that is capable of accepting MathLink packets. This option may be useful when the front end is used as a typesetting or graphics rendering service.

-nosingleLaunch. Allows multiple front ends to be running on the same display. This is the default.

-noSplashScreen. Prevents the splash screen from being displayed on startup.

-nostderrWindow. Tells the front end not to display stderr messages in a pop-up window.

-nowatchCLIPBOARD. If specified, the X front end will not watch the CLIPBOARD property for change in ownership. The CLIPBOARD property allows items to be shared between X applications via Copy and Paste commands. If this option is specified, you can only paste items within Mathematica; items pasted into the CLIPBOARD from other applications are ignored.

-preferencesDirectory. Allows you to specify the location where preferences are stored. By default this is set to ~/.Mathematica/FrontEnd.

-primaryModifierMask. Specifies the modifier mask to use as the command key. The default is Mod1Mask.

-printCommand. Takes one argument that should be a command that sends the file to the printer, such as lpr or lp. This command appears in the Print dialog box. If the -printCommand option has been used before and it is used again without first clearing the "Print To" field in the Print dialog box, the option will not work. If Mathematica is started with the -cleanStart option, the -printCommand option will work again.

-pureKeys. Disables key bindings involving modifier keys that are defined by the operating system. This option may need to be given in order for some front end keyboard commands to work correctly. For example, some systems may reserve 6 for internal use and then the front end cannot use this to typeset superscripts. Key bindings involving the key are not disabled by this option.

-pwfile. Tells the front end to get its password from the specified file.

-pwpath. Tells the front end to search along the specified path for a mathpass file containing a valid password.

-querySingleLaunch. Brings up a dialog box to ask the user if a file specified on the command line should be opened in the currently running front end. The dialog box appears only if the current front end was also launched with the -querySingleLaunch option.

-screenXResolution. Specifies the horizontal screen resolution of the notebook display in dots per inch. For example, if the default screen resolution is 75 dpi, setting the option to 150 causes the contents of the notebook window to scale horizontally by a factor of two.

-screenYResolution. Specifies the vertical screen resolution of the notebook display in dots per inch. For example, if the default screen resolution is 75 dpi, setting the option to 150 causes the contents of the notebook window to scale vertically by a factor of two.

-secondaryModifierMask. Gives the modifier mask to use as the option key. The default is Mod2Mask.

-singleLaunch. Allows only one copy of the front end to exist per display. Multiple launches are prevented only if the currently running front end was launched with the -singleLaunch or -querySingleLaunch option.

-topDirectory. Specifies the directory where Mathematica is installed, typically /usr/local/mathematica.

-version. Prints the version number of the front end from the command line.

-visualChooser. Starts the front end by first putting up the Visual Chooser. This is a dialog box that allows you to specify system parameters such as visual ID, depth, and colormap.

-watchCLIPBOARD. Tells the front end to watch the CLIPBOARD property for a change in ownership. This is the default. The CLIPBOARD property allows items to be shared between X applications. If this option is set, then you can paste items into Mathematica from other applications.

-wwwBrowser. Gives the command to execute when opening URL links from the front end. The command can include a %s format argument that is replaced with the URL.

Kernel command-line options

-initfile. Lists the name of a file that contains commands that should be run on startup.

-initpath. Is followed by a path to search for an initialization file called init.m.

-mathlink. Specifies that the kernel should be run in MathLink mode.

-noinit. Specifies that no initialization file should be read at startup.

-password. Takes one argument, which should be a valid password. The argument should have the form "machine MathID licensenumber password".

-pwfile. Specifies the name of a file that has a valid password.

-pwpath. Specifies a path to search for a file called mathpass, which stores a valid password.

-run. Is followed by a command to run immediately on startup.