This content is dedicated to our next version. It is work in progress: its content will evolve until the new version is released.

Before that time, it cannot be considered as official.

Bonita Studio preferences and configuration

Learn about deployment, web and other Bonita Studio preferences, as well as the Bonita Studio embedded Tomcat configuration.

Bonita Studio preferences

To configure Bonita Studio preferences, click Preferences in the Cool bar.

General preferences


  • Database clean-up: by default, the database (used by Bonita Engine) preserves all data when Bonita Studio exits. You can override this in order to purge all data instead, which may be useful when you are testing processes.

  • Organization load: by default, the default organization is loaded with Bonita Studio starts. You can override this.


  • Cool bar size: Normal (default) or small.

  • Grid options for process diagrams. You can choose to use a grid positioning for all new process diagrams

  • Grid spacing (in centimeters). Default: 0.5

  • Theme: Light or Dark


  • Bonita Studio language.

  • Web applications language: the language to use by default when loading process forms and Bonita Applications


  • The JDK (Java Development Kit) to used by default. JDK will be used when compiling and running Java code

Bonita Studio requires a JDK 17. If you have multiple versions of Java installed on your computer you might need to specify which Java Virtual Machine (JVM) to use.
To specify the JVM version use to run the Studio you first need to identify the appropriate file to edit.
For example if you launch the Studio using BonitaStudioCommunity.exe, the file to edit will be BonitaStudioCommunity.ini.
This file is located in your Studio installation folder.

Next you need to add a -vm option and the path to the Java runtime in the ini file (each of them on a new line).
Note the format of the -vm option − it is important to be exact:

  • The -vm option and its value (the path) must be on separate lines.

  • The value must be the full absolute or relative path to the Java executable, not just to the Java home directory.

  • The -vm option must occur after the other Bonita-specific options (such as -product, --launcher.*, etc), but before the -vmargs option, since everything after -vmargs is passed directly to the JVM.

For example on Windows:


Deployment preferences

Run mode

  • Validation: whether to validate the process before it runs. We recommend keeping this option enabled.

Server settings

  • Start engine server at launch: by default, the Runtime server is started when the Studio starts up. You may choose not to start the Runtime server until it is actually needed, that is, when you first deploy a new process/organization/BDM/…​ or when you launch the UI Designer for the first time.

  • Custom page debug mode: When enabled, custom pages classloader are rebuilt at each call. Can be useful when updating custom page source directly from cache folder (<tomcat_folder>/server/temp/bonita_portal_<id>_@hostname/tenants/<tenantId>/pages/<custompage_folder>)

  • Port number: Studio embedded Tomcat HTTP listening port.

  • Tomcat Maximum memory allocation (in Mb): the maximum memory allocation (Xmx) for the heap of the JVM running the Tomcat server. Default: 512

  • Tomcat JVM additional arguments: additional java arguments to be passed to the Tomcat JVM at startup. e.g.: -XX:+HeapDumpOnOutOfMemory

  • UI Designer JVM options: additional java arguments to be passed to the UI Designer at startup. e.g.: -Xmx256m

Database connectors

  • Manage the JDBC drivers associated with database connectors. You should use that to include JDBC drivers for commercial DBMS (e.g. DB2)



  • Define the access to your extensions (Connectors, REST API Extensions, Themes and Actor Filters). You can configure the Maven settings such as the repositories, servers, proxies and mirrors.

Web preferences


  • Specify the web browser used when a web page is displayed. Note that some application might override this setting and use a different browser


  • HTTP Proxy settings for web access

Other preferences


  • Define the validation to be applied to the different components of your project: Business Data Model, Connector validation, KPI validation, and Processes.

You can activate this option for Business users so that they can create and share processes without worrying about the technical constraints


  • Rename diagram the first time it is saved.

  • Do not show confirmation on connector definition edition.

Eclipse Give access to all Eclipse settings (Bonita Studio is based on Eclipse)

Bonita Studio embedded Tomcat configuration

Default configuration

  • Embedded Tomcat listens on the following ports:

    • 8080: HTTP. This value can be modified using Bonita Studio preferences (see above).

    • 8006: shutdown.

    • 8009: AJP.

    • 9091: embedded h2 database server.

  • Bonita Studio also uses the following port:

    • 6969: watchdog

Changing the configuration

You might need to edit the Tomcat configuration files for example to:

  • Configure logging

  • Change listening ports (shutdown, AJP, h2) to prevent conflicts

  • Declare a datasource to connect to a business database

The Tomcat configuration files are located in the Bonita Studio workspace/tomcat/conf folder.

  • To change a port number, edit server.xml.

  • To add a data source, edit context.xml or workspace/tomcat/conf/Catalina/localhost/bonita.xml.

For more details, see the Tomcat documentation.


Symptom: You see the following error in your Studio log file

!ENTRY 4 0 2021-06-11 08:45:59.981
        at Source)
        at Source)
        at Source)
        at Source)
        at Source)

Potential cause

You connect to the internet through Proxy.

Possible solution

You need to configure your HTTP Proxy settings in the Studio Preferences > Web > Proxy.

Symptom: The Studio randomly crashes on Linux when using Wayland communication protocol (Unbuntu 22.04 default)


# A fatal error has been detected by the Java Runtime Environment:
#  SIGSEGV (0xb) at pc=0x00007fd1f85e23c4, pid=47397, tid=47398
# JRE version: OpenJDK Runtime Environment Temurin-17.0.10+7 (17.0.10+7) (build 17.0.10+7)
# Java VM: OpenJDK 64-Bit Server VM Temurin-17.0.10+7 (17.0.10+7, mixed mode, tiered, compressed oops, compressed class ptrs, g1 gc, linux-amd64)
# Problematic frame:
# C  []  cairo_region_num_rectangles+0x4
# Core dump will be written. Default location: Core dumps may be processed with "/usr/share/apport/apport -p%p -s%s -c%c -d%d -P%P -u%u -g%g -- %E" (or dumping to BonitaStudioCommunity/core.47397)
# If you would like to submit a bug report, please visit:
# The crash happened outside the Java Virtual Machine in native code.
# See problematic frame for where to report the bug.

Potential cause

Possible solution

The current workaround is to force the usage of X11 instead of Wayland. This can be achieved by starting the Studio using the following command line:

~/BonitaStudio>GDK_BACKEND=x11 ./BonitaStudioCommunity