Skip to end of metadata
Go to start of metadata


Current image captchas tests are not very accessible, and this is a major concern for us.
There is currently no consensus around this issue, but some solutions are rising.
See :


Question :
Argh! :

com.octo.captcha.CaptchaException: java.lang.InternalError: Can"t connect to X11 window server using ":0.0" as the value of the DISPLAY variable.
No X11 DISPLAY variable was
set, but this program performed an operation which requires it.

Answer :
You have correcly find out what is wrong : by default, you need a XServer to use jcaptcha. the java Toolkit use it to build images.

First of all if jcaptcha running on a 1.4 or higher JDK be sure you run your jvm with the:


This should solve the problem.
The captcha team (in fact mathieu) had a thought about this and designed a ToolkitFactory helper class.
It provides a way to avoid the installation of a xserver. This trick is documented
in the javadoc.

 * Description: This Factory is used in order to switch from the
 * java.awt.Toolkit component to other implementation like <a href="">PJA Toolkit</a>. By default this factory
 * return the java.awt.Toolkit object.
 But if the the parameter
 * <code>toolkit.implementation</code> is fixed as a parameter of the virtual machine with
 * the value of the class name of another implementation of Toolkit, this
 * factory return an implementation of this class. For exemple if you set to
 * your virtual machine <code>-Dtoolkit.implementation=com.eteks.awt.PJAToolkit</code>, the
 * factory returns an implementation of com.eteks.awt.PJAToolkit

See also :


Image generation is a very heavy process : it cost a lot of CPU and RAM.
A particular attention has been given to performance in the devellopement and test process of JCaptcha.
In order to achieve transparency on this subject, the framework is heavily load tested, and tests results are provided in the source distribution.
The tests are currently run on various plateforms including wintel, linux, and sparc/ux.
We encourage you to run and publish the load tests on your own production platform...
Load tests concerns :

  • JCaptcha engines integration load tests: to compare the CPU/RAM cost of a particular captcha test generation
  • JCaptcha services mocked load tests: to compare the CPU/RAM cost of a particular life cycle management strategy
  • JCaptcha services integration load tests: to compare the CPU/RAM cost of a particular life cycle management strategy with a particular
    To run load tests, simply run maven having this line commented in the file :
    see :

Management and JMX

The jcaptcha service provide some jmx facilities.
A manageable service provides :

  • Runtime engine switch
  • Usage and success statistics
  • Cache and Buffer management
    The current implementation of the ManageableCaptchaService interface is JMX enabled.
    All modules includes a JMX registration parameter that automatically register the Jcaptcha Service
    to a JMX server.
    See modules documentation and java docs for details.

TODO : refactor the FAQ

  • No labels