brat troubleshooting

This document provides information on how to address specific problems with brat. For general instructions on use, see the brat manual.

If you have encountered a new issue with brat that is not addressed here, please file an issue report on the brat issue tracker on github.

Trouble using brat

This section relates to issues using an existing brat installation that has been working for other users (client and UI issues). If you have trouble creating a new installation of brat on a server, skip to the section on installation.

1) brat fails to start, or some features do not work

Sidebar: why is browser X not supported?

Most likely because the browser does not fully implement support for Scalable Vector Graphics (SVG).

The core of brat visualization is based on SVG. Although SVG has been a recommended web standard for over a decade, not all browsers have implemented it; in particular, Internet Explorer has only started supporting SVG from version 9. Because SVG is central to the brat visualization, supporting browsers that do not implement it would require rewriting much of the brat client. There are currently no plans to do this, and we ask users of browsers that do not implement SVG support to consider using one of the many supported browsers when using brat.

It may be that your browser is not fully supported. Please check your browser on the brat browser support page.

If your browser is listed as supported but brat fails to work, please check the following:

JavaScript should be permitted. The layout and editing functions of brat are implemented in JavaScript, and having JavaScript switched off either entirely or limited using blockers such as NoScript will prevent brat from working.
Cookies should be permitted for editing. brat identifies users by a session cookie, so users who refuse cookies cannot be verified as having editing permissions. (Cookies can be switched off for visualization.)
The browser should be a relatively recent version. Older versions of supported browsers may work partially or not at all. Please consider upgrading if you are running an older version.

If your browser is listed as not supported, please consider installing a supported browser. Most of the supported browsers are freely available, and installation only takes a couple of minutes. (You can also try pushing the brat developers to improve support for your browser!)

2) brat works, but is slow

This issue may relate to the browser, the system used to run it, server load, or document size.

Browser implementations of the core technologies used to implement brat (vector graphics and JavaScript) have greatly improved recently, and installing the latest version of your favorite browser may resolve the issue. There are also known differences in the efficiency of various browsers' implementations of these technologies, and trying a different browser may help. brat is known to work well on recent versions of the Google Chrome and Apple Safari browsers.

System requirements for running the brat client are not high, and most modern machines (including laptops) should be able to run brat without noticeable slowdown. However, low-powered or memory-limited platforms such as smartphones and older tablets as well as old machines may be unable to run efficiently. Processing and memory requirements can be reduced by limiting the size of collections and documents accessed on such devices.

Server requirements for running brat are also quite modest, but heavy server load will be noticed also as slowdown on brat clients accessing the server. If you are running both the brat client and server on the same machine, try closing down other programs to release server resources.

Document size increases processing power requirements on brat. The system does not yet implement progressive or partial rendering; that is, the whole document is always rendered even though most of it may not be shown on-screen. Additionally, the brat validation functionality also lacks support for progressive validation and the whole document is checked against its annotation configuration for each annotation made. We hope to address these limitations in a future release, but for the current version we suggest to partition large documents into smaller sections for annotation. A work around is also to disable the validation functionality in tools.conf. Additionally, dense annotations also increases the load on the rendering component due to additional layout requirements. Thusly, a document size that may be fine for sparse annotations (e.g. named entities) may prove challenging for very dense annotations (e.g. syntactic dependencies) than contain a multitude of spans and relations since every token is to be annotated.

3) brat was working, but crashed or misbehaved

(in short: try reloading the page.)

You may have encountered a bug in brat. Please contact the developers or use the brat issue tracker to report the issue! We should be able to fix this, in particular if the issue repeats when you perform a particular sequence of actions.

(It is also possible that you are encountering a browser bug. Though relatively rare, they do occur. In this case updating your browser might help.)

In general, you should be able to recover from a brat "crash" or "hang" simply by reloading the page in your browser (or, in case of browser bug, reloading the browser). It is always safe to reload brat: you will not lose any of your work; all annotations are immediately stored on the server as soon as you make them.

Trouble installing brat on a server

Install script fails to set groups

The install script may output "failed to change group.", signaling that a step in the installation did not work as expected.

The install script (install.sh) attempts to assign the data and work directories to the web server group by default. This requires superuser permissions, and will fail if you do not have these permissions or mistype your password. If setting the group fails, the webserver will fall back on assigning full permissions to the data and work directories to all users. This is less secure, but may be acceptable e.g. on systems with only trusted users, and should allow the brat server to work.

You can either set the permissions manually after installation or ask your system administrator to assign the data and work directories to the web server group.

There is no response at all from the brat server

This indicates problems with yor web server configuration. It may be that there is no web server installed, the web server is not running, or that the server does not have permissions to access the brat directory.

Please check your web server setup or contact your system administrator.

Only a defunct menu bar on a blank screen is shown

It is possible that the brat server script ajax.cgi is not being executed as a CGI script by your web server.

To check if this is the case, point a browser directly at the ajax.cgi script: if your brat installation is located at, for example, http://127.0.0.1/~brat/, try entering the URL http://127.0.0.1/~brat/ajax.cgi. If this gives an "internal server error" or similar message, the script is not being executed. (If you receive a "no action" message from brat, the issue is elsewhere.)

To fix this, verify that your web server is configured to allow the execution of CGI scripts in the directory into which brat is installed (see installation instructions) and that the script ajax.cgi is executable by the web server.

brat server fails on "Incompatible Python version"

The brat server is written to support python versions 2.5 and above in the 2.x series. If your python version is older, you may need to install a newer version of python to run brat.

You may also be seeing this message if multiple versions of python are installed on your system, even if some of these are compatible with brat. The version of python used by brat is determined by the env command by default, and you can determine this version by running env python --version. You can change the version of python used by the brat server either by changing the web server path settings (potentially risky) or by editing the first line of the file ajax.cgi in the brat server root directory to directly invoke a compatible version.

An "Open" dialog is shown, but there is nothing to open

This indicates that there is no data set up on your server. This is expected immediately after setting up a new brat server on older versions of brat. For v1.3 and above, the example-data/ directory should be set up during installation.

You can either set up data as indicated in the installation instructions or import documents using the brat UI, from the "Data" dialog accessible from the blue bar on top.

A working brat installation failed when upgrading to v1.3 (Crunchy Frog)

Please see the page on upgrading to v1.3 for information on issues relating to upgrading.