1. Help Center
  2. Getting started
  3. Transkribus eXpert (deprecated)

Troubleshooting Transkribus eXpert (deprecated)

This article will help you to troubleshoot the deprecated desktop version of Transkribus.


Please note that Transkribus eXpert (desktop software) is no longer being updated, and all new features will be exclusively available on the Transkribus web app.


      • If you do not have “Administrator” rights, Windows will produce a warning message, such as: “Your Computer is Protected by Windows.” Do not confirm, but go to “More Information”. There you can agree that this is not malware and that you want to run Transkribus on your computer.

      • Transkribus eXpert requires Windows 64 bit. If Transkribus does not start, it may be because a 32 bit operating system is installed. Then a new 64 bit operating system would have to be installed.
        To find out your operating system, go to Windows Settings – About or run Transkribus from the console to get a more detailed error message. To do this, type ‘cmd’ in the Windows search, open the ‘Command Prompt’. Then change to the Transkribus folder with cd ‘Transkribus directory’ (e.g. cd C:UsersUsernameTranskribus-1.20.0) and run ‘java -jar Transkribus.exe’.

      • Make sure you have a 64-bit version of Java installed on your computer that is not older than Java 11.

      • To find out the Java version on your own computer, start the console again and type java -version. Then the current version will be displayed. If no java version is displayed, then the operating system cannot (yet) find the installed Java. Then a reboot or setting the ‘PATH’ variable can help: https://michster.de/wie-setze-ich-die-path-umgebungsvariablen-unter-windows-10/

      • In case of Java problems, the Java package can also be copied directly into the Transkribus folder. The Java package must be renamed to ‘jre’, so that Transkribus then uses this Java.


    • If you run the program the first time, it may not start because it is a non-signed application (“… can’t be opened because it is from an unidentified developer” message).
      In this case, right-click (or control-click) the application and choose “Open”. In the appearing dialog box, click “Open” again.

      Alternatively, right click the Track Pad to open the Context Menu and add a security exception for Transkribus.

      Another option: right-click on the program icon -> Open (in the context menu) -> via Terminal.

    • If the app won’t start at all: you can try to move the application out of the Download folder, i.e. copy or move the package to another destination folder like the Desktop or the Application folder.

    • Error message when trying to start the app from a terminal using ‘open -a Transkribus.app’ is: LSOpenURLsWithRole() failed for the application /Users/xxx/Desktop/Transkribus.app with error -10810.

      A workaround for starting the program anyhow until then is to start a new terminal (search for ‘terminal’ after hitting cmd + space), then cd into the directory where Transkribus was unpacked, e.g. the ‘Downloads’ directory. Then start the program directly from the start script that is included in the Transkribus.app package: ./Transkribus.app/Contents/MacOS/Transkribus


        • If the OS is based on Ubuntu 17.04, installing libwebkit is necessary: sudo apt install libwebkitgtk-1.0-0

    Run Transkribus via command line

    Transkribus is contained in the main jar file Transkribus-<version>.jarTo run the program from command line type: java -jar Transkribus-<version>.jarNote: Java 11 or one of the following versions is needed. Some problems (mainly Java heap space) occur because a Java 32 bit version is installed on a 64 bit operating system.To run the scripts in Mac (or Linux) you may have to make them executable from the command line: (any version before 0.6.8)

    • Mac console basics
    • change into the program folder using ‘cd’ commands
    • chmod +x Transkribus.command (or chmod +x Transkribus.sh for Linux!)


    Furthermore, you will find several files in the Transkribus package copied to your computer:

    • config.properties can be modified to adjust simple appearance properties
    • virtualKeyboards.xml can be used to specify a set of virtual keyboards
    • logback.xml can be modified to adjust logging properties (for expert users only)


    The ‘libs’ subfolder contains the necessary libraries for all platforms. Currently supported are:

    • Windows 32/64 bit
    • Linux 32/64 bit
    • OSX 64 bit

    Using a proxy server

    If you keep getting the error message “Login failed: already connected” the problem can be the proxy server.

    When the program has started, click on the home menu button on the top left and select “Proxy settings…”. In the following dialog you can set the proxy host, port, user name (optional) and password (optional). This is the recommended method for using a proxy server.

    Alternatively, you can edit the start script (e.g. Transkribus.bat on Windows, Transkribus.sh on Linux) to include the environment variables for the proxy server:

     java -Dhttps.proxyHost=<proxyserver>


            -Dhttps.proxyUser=<user name for proxy>   

            -Dhttps.proxyPassword=<password for proxy>

            -jar Transkribus-0.14.0.jar

    However, editing this file will be necessary on each update of Transkribus.

    Known Issues

    Logging in to the server is not possible via Transkribus eXpert, but on the website it works.

    • A reason for the error message “Already connected” is that your Java installation may be outdated and can’t establish a secure connection to the server. You can check your installed version by opening a terminal/command line and entering “java -version”.
      If you encounter this problem, try updating Java on your machine. We recommend a current version not older than Java 11 (Oracle or OpenJdk).
      The Mac version of Transkribus includes a Java runtime. If you encounter this problem on a Mac please download a new package from https://readcoop.eu/ and update your installation.
      If the error persists please contact info@readcoop.eu, ideally including the log file of your installation (from the Transkribus directory: logs/TrpGui.log) and/or information on your Java version and operating system.
    • Note: the Mac version of the expert client comes with a java shipped within the application. If this java version is outdated, you can try to delete or replace it with an updated version. To find the files in Mac finder, right-click (or cmd-click) on the Transkribus application in your programs view, click “show packages contents” in the context menu, then go to the subfolder “Contents/MacOS”. There, the subfolder “jre” contains that java version. If you delete this folder, the application starter will try to find java on your system.
    • You may have to configure a proxy server via ‘main menu’ – ‘Proxy settings’.

    Wrong JAVA Version on Mac

    • After opening the command file on the Mac, Transkribus says that there is a wrong Java version installed. However, there is the most current version of Java installed. The problem is that an older version may still be installed and set as default Java. You can check the default version by opening the terminal and typing ‘java -version’.
    • To solve the problem you can either download the latest Java versions as a .tar.gz package from here: https://www.oracle.com/java/technologies/downloads/ and unpack it into the Transkribus folder – the Transkribus.command file will automatically check for java installations in its sub directories.


    Java Heap space / No more handles

    • 32 bit Java on a 64 bit Windows OS -> install 64 bit Java from here: https://www.oracle.com/java/technologies/downloads/
    • Too little RAM: Try to allocate more main memory by opening Transkribus.bat and set e.g. java -Xmx2048m -jar Transkribus-1.14.0.jar
      Start Transkribus with this bat file


    Logging in is prevented by the Firewall of your Internet Provider

    • Some IT departments are blocking the SSL port 443 and/or unknown applications via a firewall. Please check with your IT department if that might be the case.


    Avira or Norton Antivirus detects a threat and is blocking the zip file from being unpacked.

    • Solution: This is a false alarm which Norton gives when encountering software it is not familiar with (WS.Reputation.1). You should be able to restore the file from quarantine by following the instructions from this resource.


    Transkribus does not start on (Fedora) Linux – ‘MOZILLA_FIVE_HOME not set’ error message

    • The package “libwebkitgtk” may not be installed. On Fedora you can install the package using dnf on the command line (use “yum” instead of “dnf” in older versions of Fedora): sudo dnf install webkitgtk


    Dark mode on Mac

    • The dark mode on a Mac can sometimes cause problems with Transkribus, so if Transkribus does not run properly on your Mac and you have the dark mode switched on, please try to turn it off. You might need to reinstall Transkribus after turning off the dark mode in order to take the change into effect.