BotDetect CAPTCHA Java FAQ

This page will contain answers to frequently asked questions about BotDetect Java Captcha deployment and integration.

CAPTCHA Java Integration & Deployment

Which version of Java is required to run BotDetect Captcha Java library??

BotDetect Java Captcha library requires Java 5 or higher.

Which version of servlet is required to run BotDetect?

BotDetect Java Captcha library requires Servlet 2.3 or higher.

Which version of JSP is supported by BotDetect Captcha Java library?

BotDetect Java Captcha library works with JSP 2.0 or higher.

Does BotDetect Java Captcha library work in JSF 1.x JSF 2.x?

BotDetect Java Captcha library works with JSF 1.2 or higher.

I'm trying to use BotDetect in my Java website but Captcha images are broken / don't display at all. When I open the image Url in a new browser tab, I get 404 Not Found or 403 Forbidden errors.

BotDetect uses CaptchaServlet class to serve Captcha images and sounds. For BotDetect to work properly, you must ensure that you have registered CaptchaServlet in your WEB-INF/web.xml file.

Does BotDetect Java Captcha library require Java Servlet Session state?

Traditional API requires Java Servlet Sessions.

Simple API doesn't require Java Servlet Sessions since BotDetect uses embedded HSQLDB database to persist its data on a server side. In paid version this persistence provider can be customized to use Memcached or Redis.

I'm facing an issue with the default BotDetect Sound folder
(WEB-INF\BotDetectSounds) in my Oracle WebLogic Server. I have put BotDetect sound package in this folder, but it does not work.

Yes, it does not work by default. Because we have used the getRealPath() to determine the real system WEB-INF\BotDetectSounds path in the BotDetect Java Captcha library, this method returns null in Oracle WebLogic Server by default.

To make BotDetect Sounds works, you will need to change the behavior of getRealPath() by using the following configuration in your weblogic.xml file:


How can I find out which version of BotDetect Java I currently run?

Use the follownig API to find out which version of BotDetect Java you run:


My website uses Global content delivery network (CDN). Is there anything I should take care of in order to assure that BotDetect works?

BotDetect will not work if BotDetect markup is added to webform on a server side, and then forms with Captcha are delivered through CDN.

Basically, the issue is that BotDetect markup that is added into your webform markup contains some parameters that are unique for each rendered Captcha.

Delivery through CDN freeze this parameters to values that are stored in CDN, and therefore Captcha fails to display, validate (or both depending of your implementation).

There are 2 ways to resolve this issue:

  • To exclude webform containing BotDetect markup from being served through CDN:

    All of other content referenced (styles, images, scripts, etc...) in your web page source, can still be served through CDN so there will be no larger performance penalty.


  • To add BotDetect markup to your webform with JavaScript.

Please note:

Whatever approach you decide to go with, you still MUST exclude /botdetectcaptcha urls from being served through CDN.

We have JavaScript-based frontend (jQuery, Angular, React, ...) and we would like to set the locale dynamically on a client side rather than hard coding it on the server side. How to read the locale from our request parameter and change the Captcha locale dynamically?

When you need to support different locales in the same form, you'll need to define the new Captcha style (in botdetect.xml) for each supported locale.

When visitor changes locale on a client side, you need to request the new Captcha instance based on the new (locale-specific) Captcha style from your back-end, and load that newly generated Captcha image on a client side.

Here is the example of botdetect.xml configuration file with locale-specific styles:

<?xml version="1.0" encoding="UTF-8"?>






Examples of usage in various JavaScript frontends:

1. jQuery

<script type="text/javascript">
    var captchaLocaleStyleName = 'loginCaptcha_en';
    var captchaDirectiveElement = 
      '<div id="botdetect-captcha" data-stylename="'
      + captchaLocaleStyleName + '"></div>';

2. Angular

const captchaLocaleStyleName = 'loginCaptcha_en';
<botdetect-captcha styleName={{captchaLocaleStyleName}}></botdetect-captcha>

3. AngularJS

$scope.captchaLocaleStyleName = 'loginCaptcha_en';
<botdetect-captcha styleName={{captchaLocaleStyleName}}></botdetect-captcha>

4. React

const captchaLocaleStyleName = 'loginCaptcha_en';
    ref={(captcha) => {this.captcha = captcha}} 

Java CAPTCHA Validation & Security

The BotDetect Captcha image displays correctly on my page, but the Java form is submitted regardless of the Captcha code entered.

You have most likely forgotten to include Captcha validation code in the Java script that processes your form's submitted data. You can see an example code snippet for Captcha validation in the How To Add BotDetect CAPTCHA Protection to JSP forms guide.

Also, you might want to take a look at the BotDetect Java integration examples that come with BotDetect downloads, starting with the JavaServer Pages Basic CAPTCHA integration code example.

Why can't users correct their Captcha code input when they get it wrong? If they make a mistake, it seems they have to type in a whole new code from a new image.

You are right, and this behavior of the Captcha component is by design. Only one validation attempt is allowed per Captcha code for security purposes.

If we allowed multiple retries on solving the same Captcha, it would significantly lower the Captcha security, since bots could just brute-force different code values until they eventually got it right. Also, it would be much easier to write a bot which used OCR techniques to bypass the Captcha: if, for example, it could recognize two out of the five digits in the image, it would just have to brute-force the remaining three.

So a failed validation attempt (whether on the client- or server-side) always invalidates the current Captcha code. Successful server-side validations also remove the code (so we prevent cases where somebody solves just one Captcha and then keeps reusing it for multiple submissions).

Successful client-side validations (using the ValidationAttemptOrigin.CLIENT value) are the only ones that don't invalidate the current code, so you can also validate the same submitted values on the server-side once all form fields have been filled-out.

So basically, if the Captcha validation attempt wasn't successful, the Captcha image also needs to be reloaded and the previous user input cleared, since the old Captcha code has been invalidated.

I want to validate the Captcha code input on the client side without submitting the Java form. Do you have any suggestions?

If you want to avoid full page submissions, you could take a look at the JavaServer Pages jQuery CAPTCHA integration example coming with the BotDetect download, which uses Ajax requests to only submit Captcha validation data to the server and update the client display based on the Captcha validation result.

Pure client-side CAPTCHA validation drawbacks

Pure client-side Captcha validation (without any communication with the server) is not supported by BotDetect, since such a Captcha is trivial to bypass, and doesn't provide any serious protection from bots. For example:

  • You want users to post comments only if they have successfully solved the Captcha.
  • If the Captcha validation is purely client-side, this means JavaScript code must send the user's comment to the server when the Captcha code is entered correctly.
  • So the spammer only needs to solve the Captcha once, and note how you handle the result: e.g. sending a specific POST parameter, or redirecting to a specific page.
  • After that, they can simulate the same behavior in their bot and bypass the Captcha completely – by simply faking the POST parameter, or accessing the redirection landing page directly.
  • You can back the client-side Captcha validation by also validating the same user input on the server once the page is posted and before recording the user comment.
  • But since you are keeping the correct Captcha solution on the client for validation, bots can have easy access to that code and then always solve the Captcha correctly.

The exact details would of course depend on your specific use-case and Captcha integration scenario. But essentially, all client-side code is insecure and can be faked or modified by malicious parties. As a consequence, Captcha codes must only be kept on the server, and all Captcha validation must be performed on the server as well.

Client-side Captcha validation - the solution

You can avoid full page submissions by using Ajax to make asynchronous Captcha validation requests to the server, and processing the result on the client:

  • When the Ajax Captcha validation fails, you can show the user a new Captcha image without affecting the rest of the page, thus improving the user experience and overall usability of the page.
  • You should always change the Captcha code in such cases, since allowing multiple attempts at solving the same Captcha makes OCR guessing much easier.
  • When the Ajax Captcha validation succeeds, you should then submit the page to the server and validate the user Captcha input again.
  • Only after successful server-side Captcha validation should you execute the "protected" operation (e.g. record the user comment) on the server.

What is the difference between ValidationAttemptOrigin.SERVER and ValidationAttemptOrigin.CLIENT?

The two ValidationAttemptOrigin values were added to support a specific use-case involving Ajax Captcha validation: If somebody starts with a regular full post-back Web Forms page using BotDetect Captcha, and wants to improve the accessibility of the form by performing asynchronous Captcha validation.

The improvement Ajax Captcha validation brings is that users will get faster feedback when they enter an incorrect Captcha code, and they won't have to reload the full form and other form values. When users enter a valid Captcha code, a full post-back is performed and the form is validated again on the server (since all client-side code is unsafe and can be tampered with by malicious clients).

So to support this use-case, we have to allow the same Captcha code to be successfully validated twice (once from an Ajax request, and once in the full form post-back). This is the reason why we added the ValidationAttemptOrigin.CLIENT flag, which signals the Captcha validation not to remove the successfully validated Code immediately (since it will need to be validated again in the full form post-back). All other validation attempts remove the stored Captcha code after one validation (regardless of the result) for security reasons.

In conclusion, ValidationAttemptOrigin.CLIENT is used when performing Ajax Captcha validation, and ValidationAttemptOrigin.SERVER is used when performing full post-back Captcha validation.

I have a form protected with BotDetect Captcha that contains several other validated fields. When a user enters the correct Captcha code but server-side validation of another field fails, they are shown another Captcha image with a different code.

Is there a way to show them the same Captcha image and keep the entered code, so they don't have to solve more than one Captcha just because they entered an invalid value for another field?

Users definitely shouldn't have to solve another Captcha if they enter the correct Captcha code, but (for example) username validation fails. The purpose of Captcha is to ensure the user is human, and once they solve it this purpose is fulfilled.

If you have to return them to the form because another field value needs to be corrected, it's best not to show them the Captcha at all.

See the JavaServer Pages form captcha code example to know how to display and validate the Captcha if it hasn't already been solved.

For security reasons, it is not possible to get the same BotDetect Captcha image on two page loads, nor to use the same code for more than one Captcha image.

Please Note

BotDetect Java Captcha Library v4.0.Beta3.5 is an in-progress port of BotDetect 4 Captcha, and we need you to guide our efforts towards a polished product. Please let us know if you encounter any bugs, implementation issues, or a usage scenario you would like to discuss.