Manual:Troubleshooting math display errors

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

Preliminaries

Have you compiled texvc? see the math/ directory
Do you have LaTeX, dvips, gs and convert (ImageMagick)?
Is your LaTeX installation correct?
Are the math formulas correct latex? Try a simple formula like <math>0</math>
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

Errors

Raw <math></math> Tags

Check LocalSettings.php for:

$wgUseTeX = true;

No error messages but source is displayed instead of rendered formula

Check the math directories configuration (see next section).

Everything below is saying that

$wgMathPath = "{$wgUploadPath}/math;"

but i had this error go away with

$wgMathPath = "/images/math";

"Failed to parse (Cannot store math image on filesystem)"

Make sure the access to the upload folder is correct (/wiki/images).

chmod -R 766 images

"Failed to parse (Can't write to or create math output directory)"

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. You can run this command if you have shell access to the server and it runs on a Unix system.

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

The tmp directory is located inside the image directory. chmod 777 tmp to make writeable. Make sure that there's no SELinux errors. If not, change the policies accordingly.

By default $wgUploadPath and $wgUploadDirectory are set to false. You can specify explicit full URI for $wgMathPath and absolute path for $wgMathDirectory and $wgTmpDirectory. The $wgMathDirectory variable must be the path on the file system of a folder accessible from HTTP, and $wgMathPath must be the corresponding path in URL.

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

I got it to run on a host. First

#apt-get install mediawiki-math

then set the globals on LocalSettings.php

$IP = "/home/user/htdocs/wiki";
$wgScriptPath = "/wiki";
$wgEnableUploads = true;
$wgUseTex = true;
$wgUploadPath = "$wgScriptPath/images";
$wgUploadDirectory = "$IP/images";
$wgMathPath = "$wgUploadPath/math";
$wgMathDirectory = "$wgUploadDirectory/math";
$wgTmpDirectory = "$wgUploadDirectory/tmp";
$wgUploadBaseUrl = false; #not sure about why this one too...
$wgTexvc = "/usr/bin/texvc"; #install through apt-get instead of make on ./math

and also global rights for images/ , images/math/ and images/tmp/

user@host:~/htdocs/wiki#chmod 777 images/ images/math/ images/tmp

apache httpd restart also: # #apache2ctl restart Abacatabacaxi 02:58, 26 May 2011 (UTC)

"Failed to parse (PNG conversion failed; check for correct installation of latex, dvips, gs, and convert)"

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 this is the problem, run

apt-get install dvipng

On some Debian based systems a Latex error is logged saying cancel.sty is missing. This can be fixed by installing the texlive-latex-extra package as follows:

apt-get install texlive-latex-extra

Or on Amazon Linux run the following command:

sudo yum install -y texlive-xltxtra

More generally, if one of the other 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 dvipng

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

In case the above example didn't work: On debian, the tetex-extra package was renamed to texlive-latex-extra. If that is not installed, latex will not render a dvi from the generated tex files and consequently no png can be rendered.

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

This suggestion was found on [1] but has worked for more than three 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.

Permissions checks: make sure that the apache user has the ability to execute the texvc executable, and write to the /images folder. Turn on logging, then try to refresh a page with a preview fomula in it, to see what happens in the logs. This should point you to where the texvc file is running, on my server it was in the /tmp folder. There were .tex and .log files in the /tmp folder, and the log file showed me the answer to my problem: I needed both cancel.sty and latex.fmt in the /tmp folder in order for texvc to run happily there.

Build all dependencies from source: including libpng, libgd, dvipng, ocaml and ocamlopt (with 'make opt'), and texvc. Link the libs for each dependency at each step, or just copy / install all the libs them into /usr/lib or /usr/bin and all the headers into /usr/bin/include as you go. Go into the extensions/Math/math subfolder and run './texvc . . "x=y+2"' to make sure it works there with no errors.

Mac

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.

Note: It might be a path problem in the render.ml file of texvc. See here

Nginx : Execute texvc as root with sudo

After we changed over from Apache to Nginx I found that the texvc binary would no longer produce the PNG file. The binary was being executed properly by shell_exec in MathTexvc.php, but for some reason would not build the image even though other scripts would run such as for rendering thumbnails etc.

I couldn't find anything logged about a problem anywhere in the system, and there were no differences in PHP configuration that I could find. I tried adjusting render.ml to leave the temporary files so I could analyse those (by removing the lines deleting then from the unlink_all function then running name clean and make to rebuild the texvc binary, but it wouldn't produce any of the files except the .tex one.

The only working solution I could come up with was to run the texvc as root using sudo by changing line 149 of MathTexvc.php as follows:

$contents = wfShellExec( "sudo $cmd" );

To allow the web-server to have sudo access without compromising security the following line can be added to /etc/sudoers:

www-data ALL=NOPASSWD: /path/to/wiki/extensions/Math/math/texvc

To make this solution secure, you need to be sure that no one will be able to edit the texvc file. If you can't try the next solution.

Nginx : Use absolute path in texvc sources

The solution described bellow works for me (the precedent too), but I really don't know why. It just seem that the latex and `dvips` command won't start if they are called from php. They return nothing except 134, I still don't know the meaning of this. If I try to do latex -v, it will give you the normal message, so it works and it's not really a path problem. But if I do /usr/bin/latex from php instead of latex, the command will work normally.

Open path/to/wiki/extensions/Math/math/render.ml and then on line 3-4 the put absolute path for dvips and latex.

On debian 7 with mediawiki 1.23.2 and Math 1.2.0 it will be :

let cmd_dvips tmpprefix = "/usr/bin/dvips -q -R -E " ^ tmpprefix ^ ".dvi -f >" ^ tmpprefix ^ ".ps"
let cmd_latex tmpprefix = "/usr/bin/latex " ^ tmpprefix ^ ".tex >/dev/null"

You can get absolute path of latex and dvips by doing

whereis latex
whereis dvips

Now go to the math directory and build texvc

cd path/to/wiki/extensions/Math/
make

And if there is no compilation problems (you need the ocaml-nox package under debian), the problem should be fixed.

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 shell command in each of the let cmd_ ... = statements.

let cmd_dvips tmpprefix = "env dvips  ...
let cmd_latex tmpprefix = "env latex ...
let cmd_convert tmpprefix finalpath = "env convert ...

Then run make 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 "<full path to gs>/gs".