Manual:Troubleshooting math display errors

In case your users encounter problems with LaTeX equations on your wiki, the following troubleshooting steps might help.

Preliminaries

 * 1) Have you compiled texvc? see the math/ directory
 * 2) Do you have LaTeX, dvips, gs and convert (ImageMagick)?
 * 3) Is your LaTeX installation correct?
 * 4) Are the math formulas correct latex?  Try a simple formula like $$0$$
 * 5) Are the file permissions correct?  Can your image directories, include images/math and images/tmp be written to by your webserver's user?

If none of these help, you might have to start rolling up your sleeves. From here on, we assume that you have some access to the web server, specifically that you are at the directory where you installed MediaWiki, for example:

cd /whatever/htdocs/w

Raw $$$$ Tags
Check LocalSettings.php for: $wgUseTeX = true;

Linux
Check your LocalSettings.php for the following global variables: $wgMathPath        = "{$wgUploadPath}/math"; $wgMathDirectory   = "{$wgUploadDirectory}/math"; $wgTmpDirectory    = "{$wgUploadDirectory}/tmp"; and make sure those directories are all writable by your webserver.

sudo chown -R www-data:www-data directory

The tmp directory is located inside the image directory. chmod 777 tmp to make writeable.

I've solved the problem in ver. 1.6.10 modifying the function wfMkdirParents in includes/GlobalFunctions.php. But I'm not sure that will work in all cases. function wfMkdirParents( $fullDir, $mode ) { $parts = explode( "/", $fullDir ); $path = ""; $dir2=""; foreach ( $parts as $dir ) { if ($dir=="images") {$dir2="images";} if ($dir2=="images") { $path = $path.$dir."/"; if ( !is_dir( $path ) ) { if ( !mkdir( $path, $mode ) ) { return false; }                                       }                        }        }        return true; }

If its impossible solve the problem changing the function wfMkdirParents you can ty this.  Open LocalSettings.php and includes/DefaultSettings In LocalSettings.php make sure that $wgScriptPath is set correctly In includes/DefaultSettings set $wgScriptPath = false 

Actually, I found changing $wgUploadBaseUrl = ""; to $wgUploadBaseUrl = false; in includes/DefaultSettings.php made everything work, rgds Sam Watkins

For me, the error "Failed to parse (Cannot write to or create math temp directory)" was solved after the command chmod 755 images was run, but I still received the error until I logged in, and re saved the page containing the Latex. -David

Linux
Make sure each of the required programs are executable by the webserver and in the webserver's PATH ls -lH `which gs` `which latex` `which dvips` `which convert`

Check also dvipng (This was the problem for me on a debian linux) ls -lH `which dvipng`

If one of these fails you may need to install the missing packages. In distributions with yum you can do the following: yum install tetex tetex-fonts tetex-dvips tetex-latex ghostscript

Try to execute from the command line.

Example:

texvc /home/wiki/tmp /home/wiki/math "y=x+2"

If the above example worked and you found the correct PNG file in /home/wiki/math, you might want to copy your latex.fmt in the $wgTmpDirectory ( usually $wgTmpDirectory = "{$wgUploadDirectory}/tmp"; ) You can find latex.fmt by  find / -name latex.fmt and then copying: cp [path to latex.fmt] $wgTmpDirectory where the $wgTmpDirectory might be wiki/images/tmp. On CentOS 5, this has been reported: cp /root/.texmf-var/web2c/latex.fmt $wgTmpDirectory Alternatively, if you have root access, you can simply run the command which the CentOS latex packages ommitted: fmtutil-sys --all

For FreeBSD, the file is found at '/usr/local/share/texmf-var/web2c/latex.fmt'.

This suggestion was found on but has worked for more than two people. If you try this, please be advised file /root/.texmf-var/web2c/latex.fmt is only created when you run the texvc command above. Perhaps someone can write what the proper solution to this work-around is. On most distributions there has been a transition from teTex to TeX Live. TeX Live seems to require the existence of a writable directory /var/www/.texlive2007/texmf-var/web2c to work properly.

Yet another possible solution: if the webserver running MediaWiki uses SElinux for enhanced security (RedHat/Fedora systems do that by default), then it may happen that the SElinux context of a file that is read or modified when running LaTex and creating a PNG may be wrong. A simple way to find out if this is a problem is to temporarily switch SElinux off (using "setenforce 0"), then to see if the error message goes away, then to re-enable SElinux (using "setenforce 1"). If the error goes away under "setenforce 0", the underlying problem needs to be fixed by the sysadmin of the webserver, e.g. by following the advice that the program "setroubleshootd" gives.

Macintosh
A hundred of various versions of LocalSetting.php have been examined. Yet, the correct combination of options is not achieved. If, after the assignment of variable $wgUseTeX value true, the diagnostics suggests to revise the latex, dvips, gs and convert, this can be done in the following way.

The commands latex, gs, dvips, convert can be located in the command line with commands which latex which convert which gs which dvips

For the latex, the path can be specified in the LocalSetting.pho setting the variable $wgLatexCommand

Perhaps, for the convert, the path can be specified assigning the value to variable $wgImageMagickConvertCommand

For the gs and dvips, the names of variables that should be assigned values are not known; variables with similar names do not appear in the prototype of the LocalSetting.php

Perhaps, the diagnostic service cannot identify, which of programs (latex, convert, gs, dvips) fail and indicates all the four, even if the only one of them fails.

If the absolute path of the texvc is changed to the relative with command $wgTexvc = '/math/texvc' then the error message changes to
 * Failed to parse (Missing texvc executable; please see math/README to configure.)

but the formulas do not appear. So, perhaps, the setting of absolute path, that causes the error message
 * Failed to parse (PNG conversion failed; check for correct installation of latex, dvips, gs, and convert)

is closer to the goal, than the indication of the relative path.

Windows
(todo)

SQL Errors
First, in your LocalSettings.php, set $wgShowSQLErrors = true; to see the problematic query in clear text temporarily. Then check if your problem is listed below:

Wrong collation / charset (usually utf8 vs. latin1)
You have probably upgraded from some older MediaWiki version to a newer one. And in your older one you didn't have math rendering enabled. Therefore, table "math" is empty. Its collation and charset are therefore still some default value and didn't get touched during UPGRADE. You can assign proper utf8 settings to it with the mysql statement alter table math CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;

Identify the error
Grep the error string in your mediawiki installation directory. For example, since I am working on a French wiki, I do something like: grep -r "La conversion en PNG" languages

This should tell you something useful, that is, an error code. Here, for example, we see that what we are dealing with is a math_image_error: languages/LanguageFr.php:"math_image_error"    => "La conversion en PNG a échouée, vérifiez l'installation de Latex, dvips, gs et convert",

Localise the error
Next you want to hunt the error down. Look in includes/Math.php and locate the bit of source code where your error code occurs. Following the example above, we see if( !file_exists( "$wgMathDirectory/{$this->hash}.png" ) ) { return $this->_error( 'math_image_error' ); }

Ah-hah. It only returns math_image_error if it can't find the png file in the math directory.

''Missing link between these sections ("Localise the error" and "Debug the heck out of things")

Debug the heck out of things
Put the following line in LocalSettings.php. Don't forget to make the file writable (a+w helps) $wgDebugLogFile = "/tmp/wiki.log";

You'll want to look for lines that begin with TeX:. What it will tell you is the command that it used to run texvc.

Try running that command yourself! If you run into problems, then you're on the right track. Does fixing these problems solve the errors? If not...

Hack texvc
One useful way to see where things go wrong is to edit the texvc source code. For example, you could replace the following line in texvc.ml like so

Before: | Render.ExternalCommandFailure s -> After: | Render.ExternalCommandFailure s -> print_string ("-Render Error-" ^ s ^ "-/Render Error-")

Go to the /math folder and run the make command again to recompile the things that were changed. Then, when you look in /tmp/wiki.log you might get more information as to which part of the process went wrong.

You could also edit the file render.ml. The following line, for example, could be modified to send errors to some temporary file instead of /dev/null: let cmd_convert tmpprefix finalpath = "convert -quality 100 -density 120 " ^ tmpprefix ^ ".ps " ^ finalpath ^ " >/dev/null 2>/dev/null"

The 2 is for stderr output. Change the line to

let cmd_convert tmpprefix finalpath = "convert -quality 100 -density 120 " ^ tmpprefix ^ ".ps " ^ finalpath ^ " >/dev/null 2>/tmp/wiki_convert_error"

and run make. Edit an equation again, and look at the file /tmp/wiki_convert_error. For example, mine says

sh: line 1: convert: command not found

even though I can run convert from the command line and it works. So I ran which convert and it told me it was in /usr/local/bin/, and I changed the line to read

let cmd_convert tmpprefix finalpath = "/usr/local/bin/convert -quality 100 -density 120 " ^ tmpprefix ^ ".ps " ^ finalpath ^ " >/dev/null 2>/tmp/wiki_convert_error"

Now at least I've changed the error in /tmp/wiki_convert_error:

sh: line 1: gs: command not found sh: line 1: gs: command not found convert: no decode delegate for this image format '/home/httpd/vhosts/exampleproblems.com/httpdocs/wiki/images/tmp/25921_8a419822395bff99de2663af8c7d7dda.ps'.

I looked for but couldn't find a place where gs was run. I don't know if it helped, but I installed AFPL Ghostscript 8.51. (I had been using GPL 8.15).

http://www.cs.wisc.edu/~ghost/doc/AFPL/get851.htm

The error message stayed the same. Then, as root, I copied /usr/local/bin/gs to /usr/bin/gs and it works now!

An other solution may be to put absolute paths in math/render.ml  as below, then to make again. (in command line: 'which dvips' gives the real path of dvips) /opt/local/bin/dvips /opt/local/bin/latex /usr/local/bin/convert /opt/local/bin/dvipng

Which latex, dvips, convert ...
Instead of filling up your /usr/bin/ directory and complicating OS updates, a more universal fix is to change render.ml to use the env</tt> shell command in each of the let cmd_ ... =</tt> statements. let cmd_dvips tmpprefix = "env dvips ... let cmd_latex tmpprefix = "env latex ... let cmd_convert tmpprefix finalpath = "env convert ...

Then run make</tt> in the math directory again. You may need to restart Apache.

Errors with convert
For those of you who are having problems with convert, something like "Unable to temporary file", it seems to be convert, for some odd reason, trying to create its temporary files in the directory in which it was run. You can fix this by prefixing the convert command with instructions to work in the /tmp directory.

let cmd_convert tmpprefix finalpath = "cd /tmp; convert -quality 100 -density 120 " ^ tmpprefix ^ ".ps " ^ finalpath ^ " >/dev/null 2>/dev/null" -- I have been pulling my hair out trying to get the math working on a windows 2000 installation. I have followed the above suggestions. It works when run with texvc command from the command line -- a .png file is created. However, when run from the Math.php script, it created the .tex, .dvi, .ps, but fails to perform the convert. I've hacked the texvc executable to hardcode all the paths because that gave me some trouble in a previous installation that I was able to get working.

I guess my question is: what does 'convert' need to work? Why does it work from the command line but not when run from within the script?

The answer is probably that 'convert' delegates some of its work to other software like 'ghostscript' (gs). If the Apache path does not include the gs directory convert won't work correctly when called from a PHP script. The solution that works fine under MacOSX is to modify the 'delegates.xml' file in the 'config' directory of ImageMagick (wherever it is under Windows) and to replace all "gs" occurences by " /gs".