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
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:
- 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.
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
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
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
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
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.