Skip to end of metadata
Go to start of metadata


Usually, it's just download, unzip & run; this page offers solutions for system-specific issues and special requirements. At the moment, there are no known Windows 8 specific problems with TextGrid.

Error „MOZILLA_FIVE_HOME not set“ (Linux)

If this error shows up at the startup of TextGridLab you will have to set the environment variable accordingly. Just add the following line to .profile or .bash_profile in the home directory of the user:

export MOZILLA_FIVE_HOME=/usr/lib/firefox

To set this in action the system may have to restart or rather the configuration has to be read again.

Java version trouble on MacOS X

TextGridLab requires a Java version greater than 6. Unfortunately, Oracle's “regular” MacOS installer for Java 8 seems to install Java in a way such that it can be found only by web browsers. To have third-party applications like TextGridLab to find Java, you will have to install the JDK, the developers' version of Java.

Furthermore it is not possible to run the TextGridLab from within the MacOS X Download folder! Please move the to your application folder and try again.

GUI is not responsible on MacOS X

TextGridLab launches, but you cannot click on any button or close the program. There was a change in Java 8, so Java must not be newer than Java 8u151 which you can get here (scroll to the table "Java SE Development Kit 8u151").

If the installation of any older version is not an option for you, we prepared a bundled package ("portable") available here.

Authentification fails (Windows 10, TextGridLab < 3.1)

Major changes in Windows 10 require a change in the file textgridlab.ini. Find this file in your TextGridLab folder and replace the last line

After a restart of the TextGridLab this change will take effect.

TextGridLab doesn't start: JVM error 13 (Windows, Linux)

You are using the wrong 32/64 bit variant of the TextGridLab. Download the other one and it will probably just start fine.

The TextGridLab variant must match that of the Java environment you are using. Windows users will typically use the 32-bit version, since Oracle's default Java installer seems to install a 32-bit Java even on 64-bit Windows systems.

TextGridLab doesn't start: The Textgridlab executable launcher was unable to locate its companion shared library (Windows)

You have not properly unzipped the TextGridLab. After downloading TextGridLab, please use a proper unzip tool like 7zip to unzip the complete contents of the archive, don't just open the ZIP file in explorer. Don't move parts of the TextGridLab folder around, always move the whole folder instead. If you want a TextGridLab icon on your desktop or in your start menu, create a shortcut. Don't unzip to very deeply nested subdirectories – Windows has a length limit for the overall path name, and TextGridLab itself uses long names for technical reasons (the missing file, e.g., can be found in a TextGridLab subdirectory like plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.200.v20150204-1316/eclipse_1608.dll). cannot be opened because it is from a non-verified developer (OS X)

It can hapen that OS X complains that the application is from a non-verified developer. Please right click on the and select "Open" (or press CTRL + left mouse click to open the context menu). This step needs to be done only once.

TextGridLab does not launch: an error has occured (OS X)

The error window will tell you that more information is in the displayed log file path. Please open the displayed file and have a look at the end of the file. If you see an entry like

Caused by: java.lang.IllegalStateException: The platform metadata area could not be written: /private/var/folders/yr/gtbbgl915jbg74s4kb3_q3qm0000gn/T/AppTranslocation/1231F14F-D417-4A89-B029-31B546924E99/d/  By default the platform writes its content
under the current working directory when the platform is launched.  Use the -data parameter to specify a different content area for the platform.

then please do the following: Right click on the and select "Show package contents".  Go to the folder "Contents". Right click on the file "Info.plist" and select "open with" other program ... and select TextEdit as editor. Now find the line <string>-showlocation</string> near the bottom and insert this new line after that line:


Save the file, close the Finder window and try to start the program TextGridLab again.

TextGridLab does not launch: an error has occured (Windows)

Please do not copy the extracted TextGridLab folder to c:\Program Files. TextGridLab needs to write to its folder and if the folder is moved to program files Windows denies the access to it. Just copy the folder somewhere under the user directory and launch TextGridLab from this location.

Browser components do not work (Linux)

If you are using Linux and the welcome screen remains blank and you get an error message when trying to login, you need to install WebKit-GTK 1.x. On Ubuntu or Debian, you may click the link above or enter

sudo apt-get install libwebkitgtk-1.0-0

in a terminal window to do so [TG-1903]. On Fedora [#9433], you additionally need to symlink the library to its old name

sudo yum install webkitgtk.i686
cd /usr/lib      # or cd /usr/lib64 on 64-bit versions
ln -s

For TextGridLab versions up to 2.0.5 you will also need to install the SWT patch as described in bug #9717 comment 4. Up-to-date TextGridLab versions already include the patch.

Login dialog incorrectly says you are offline (Ubuntu)

Due to a bug in Ubuntu, the TextGridLab might not be able to establish a secure connection to our servers, resulting in the Login dialog incorrectly telling you you're offline. When this is the case, your Java certificate store is broken, which means Java programs on your system generally cannot establish secure connections – you will see that the keystore (the file /etc/ssl/certs/java/cacerts) on your system is empty (only 32 bytes long). To fix this, open a Terminal window and enter the following two commands:

sudo dpkg --purge --force-depends ca-certificates-java
sudo apt-get install ca-certificates-java

Then quit and re-start the TextGridLab and it will work.

Problems extracting the TextGridLab ZIP (Windows XP only)

When trying to extract the TextGridLab ZIP on Windows XP and the target directory has a relatively long overall path, Windows' built-in extractor might fail: The extraction wizard asks for a password, and extracting via drag&drop causes some files to be missing, e.g. textgridlab.exe. There are two alternate solutions:

  • use a better unzip tool, e.g., 7-Zip
  • extract to a shorter path, e.g., C:\TEMP

Advanced Unicode characters not displayed correctly (Windows XP only)

Unicode characters that are beyond the BMP (i.e., codepoints above 0xFFFF, like many musical symbols) are represented using so-called surrogate pairs, i.e. by two consecutive characters from special Unicode blocks. Windows XP does support rendering these characters, but the support is not enabled out of the box. Newer versions of Windows as well as MacOS X and Linux support surrogate pairs out of the box.

To enable support for advanced unicode characters on Windows XP you need to add a key to your registry:

  1. Download the file Unicode-Surrogate-Support.reg
  2. Double-click it and confirm the dialog box
  3. Restart your Windows.


Help system does not work (Windows)

Windows users that use a desktop firewall may observe that displaying the help contents or actual help topics does not work. The reason for this is that the TextGridLab help system starts a local web server which then offers the help documents to either your preferred browser or the included tooling.

To get the help system to work in these cases you need to unblock TextGridLab in your personal firewall. Alternatively, use the online user manual. [TG-1998]

Installation of, e.g., oXygen aborts reproducibly after some download time (Windows)

Temporarily disable your virus scanner (problem observed with Avira).

Background: Installing oXygen requires downloading a rather large (~ 100MB) plugin file from their servers. This usually works fine, but Avira's anti-virus filter gets in the way: It redirects the download to a temporary location, scans the file for viruses after it has been completely downloaded and only after that passes the file on to TextGridLab's installation mechanism. To the TextGridLab's install and update component, this looks like the oXygen servers do not react to the Lab's request, and it will eventually abort with a timeout error. [TG-1965]

Antivirus software (Windows)

Users of "Avira Anti-Virus" reported troubles regarding the installation of oXygen (see above) and different tools. For example the preview within the XML editor is not available as long as a XSLT load external ressources. To get rid of this problem you can whitelist the TextGridLab for the "Realtime Protection" and the "WebGuard" or deactivate both scanners during your TextGridLab session. Furthermore users have to whitelist all external ressources for the WebGuard.

Advanced Installation Scenarios

Install the TextGridLab once for multiple users

The TextGridLab needs a writeable area on your hard disk to store settings and working data. By default, it will create and use a folder named workspace in the current working directory – this will typically be the TextGridLab's application folder. If this directory is not writeable (e.g., because an administrator installs the TextGridLab for all users to a read-only directory), you need to tell it an alternative. There are two ways to do so:

  1. As an administrator, you can edit the file textgridlab.ini in the TextGridLab application directory. Before the line containing -jvmArgs, add two lines:


    This will cause the TextGridLab to use the directory TextGridLab-Workspace in the current user's personal directory. The first line must always be -data, the second line contains the target directory; @user.home is a macro that will be expanded to the user's home directory.

  2. Alternatively, you can start the TextGridLab with the command line arguments -data @user.home/TextGridLab-Workspace (or likewise).

Deploy a portable TextGridLab including Java

Sometimes it may be desireable to deploy the TextGridLab in a setting where there is no recent Java installed on the client computers – e.g., in a workshop situation. In this case it is possible to create a TextGridLab installation that includes its own JRE, e.g., on USB drives. To do so, put the JRE in a subdirectory named jre of the TextGridLab. The TextGridLab will automatically use this Java installation.


  • No labels