Manual:Troubleshooting math display errors

This page was moved from MetaWiki.
It probably requires cleanup – please feel free to help out. In addition, some links on the page may be red; respective pages might be found at Meta. Remove this template once cleanup is complete.

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

[edit] 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 <math>0</math>
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

[edit] Errors

[edit] Raw <math></math> Tags

Check LocalSettings.php for:

$wgUseTeX = true;

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

[edit] 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.

1. Open LocalSettings.php and includes/DefaultSettings
2. In LocalSettings.php make sure that $wgScriptPath is set correctly
3. In includes/DefaultSettings set $wgScriptPath = false

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

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

[edit] 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`

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

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

This suggestion was found on [1] 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.

[edit] Windows

(todo)

[edit] 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:

[edit] 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;

[edit] 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",

[edit] 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")

[edit] 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...

[edit] 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

[edit] 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.

[edit] 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".

[edit] See Also

• Enable TeX
• Problems with texvc
• Texvc PHP Alternative