Known Issues / Limitations
This document describes known issues and limitations of parallel operation. The list may change as the tools evolve.
If you encounter an issue that is not listed here, please contact the Designer Development Team by submitting a ticket. Your feedback helps us improve the tools and is greatly appreciated.
Deployment Issues
Deployment Connection Errors (Database)
This issue affects versions before version 1.1.1 of the Experimental: Standalone Transpile and Deploy plugin.
Starting with version 1.1.1, you can use the built-in tunnels provided by the Designer.
When you use Deploy v2, you may encounter a java.sql.SQLNonTransientConnectionException or UnknownHostException similar to the following:
2026-01-02 10:36:13 [ERROR] Database error: java.sql.SQLNonTransientConnectionException: Socket fail to connect to host:address=(host=adito-db.name-of-your-cloud-system-htc1-adito-cloud.svc.cluster.local)(port=3306)(type=primary). adito-db.name-of-your-cloud-system-htc1-adito-cloud.svc.cluster.local
at org.mariadb.jdbc.client.impl.ConnectionHelper.connectSocket(ConnectionHelper.java:140)
at org.mariadb.jdbc.client.impl.StandardClient.<init>(StandardClient.java:102)
at org.mariadb.jdbc.Driver.connect(Driver.java:69)
at org.mariadb.jdbc.Driver.connect(Driver.java:95)
at org.mariadb.jdbc.Driver.connect(Driver.java:26)
at io.agroal.pool.ConnectionFactory.createConnection(ConnectionFactory.java:225)
at io.agroal.pool.ConnectionPool$CreateConnectionTask.call(ConnectionPool.java:545)
at io.agroal.pool.ConnectionPool$CreateConnectionTask.call(ConnectionPool.java:526)
at java.base@21/java.util.concurrent.FutureTask.run(FutureTask.java:317)
at io.agroal.pool.util.PriorityScheduledExecutor.beforeExecute(PriorityScheduledExecutor.java:75)
at java.base@21/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
at java.base@21/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642)
at java.base@21/java.lang.Thread.runWith(Thread.java:1596)
at java.base@21/java.lang.Thread.run(Thread.java:1583)
at org.graalvm.nativeimage.builder/com.oracle.svm.core.thread.PlatformThreads.threadStartRoutine(PlatformThreads.java:833)
at org.graalvm.nativeimage.builder/com.oracle.svm.core.windows.WindowsPlatformThreads.osThreadStartRoutine(WindowsPlatformThreads.java:210)
Caused by: java.net.UnknownHostException: adito-db.name-of-your-cloud-system-htc1-adito-cloud.svc.cluster.local
at java.base@21/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:567)
at java.base@21/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:327)
at java.base@21/java.net.Socket.connect(Socket.java:751)
at org.mariadb.jdbc.client.impl.ConnectionHelper.connectSocket(ConnectionHelper.java:134)
... 15 more
This usually indicates that the required SSH tunnels are not open on your local machine.
Fix
- Ensure Pageant is running and your SSH key is loaded.
- Download the tunnel script for your specific system from the SSP (Namespace → Tunnel → SSH-Tunnel Script for Windows).
- Execute the script to establish the connection.
- Verify the database connection with an external database tool, outside the ADITO Designer, to ensure that the tunnel is active.
The tunnels opened by the ADITO Designer are not sufficient. They are available only to the ADITO Designer, not to standalone tools such as the deployment tool.
Deployment: Driver Warnings ("Driver does not support the provided URL")
During deployment, you may see warning messages similar to the following in the logs:
[WARN ] Datasource 'postgresql': Driver does not support the provided URL: jdbc:mariadb://adito-db.name-of-your-cloud-system-htc1-adito-cloud.svc.cluster.local:3306/_____systemalias
Cause
The deployment tool supports six database systems. This warning occurs when a driver, such as PostgreSQL, evaluates a connection URL for a different database type, such as MariaDB.
Solution
You can safely ignore these warnings if the database system named in the warning, such as postgresql in the example, is not the database system used by your target.
Deployment: Inaccurate Change Detection (Oracle)
The deployment tool uses MD5 hashes to detect differences between local files and database records. With Oracle databases, a technical limitation affects this process.
Technical Limitation
Oracle's internal functions can only compute MD5 hashes for the first 32 KB of a BLOB field.
Impact
- Files exceeding 32 KB may be incorrectly flagged as "changed" or "unchanged" because only the beginning of the file is compared.
- Change detection is less reliable for large files on Oracle compared to other supported database systems, which hash the entire file content.
Recommendation
When deploying to Oracle systems, manually verify changes to large files if the automated detection produces unexpected results.
Working with parallel operation
VS Code cannot be started from the ADITO Designer
The Open in Extension Pack action does not open VS Code.
Workaround
- Ensure that VS Code is correctly installed on your system.
- Ensure that the CLI location of VS Code is correctly set in the ADITO Designer settings under
Settings → ADITO → Transpile and Deploy → Extension Pack Location.
Custom YAML locations are not preserved
When a project is converted to AOD and then back to YAML, data models are placed in the default location. A custom file-system location, such as my-project/ADITO/processes/auth/MyAuth_lib, is changed to processes/MyAuth_lib.
This limitation will be addressed in a later release. There is currently no workaround.
A process reference is removed automatically
When converting from YAML to AOD, a process reference may disappear from an AOD file. In the example below, the converter removes the displayValueProcess reference because the referenced file does not exist.
<entityField>
<name>CAR</name>
<valueProcess>%aditoprj%/entity/Car_entity/entityfields/car/valueProcess.js</valueProcess>
- <displayValueProcess>%aditoprj%/entity/Car_entity/entityfields/car/displayValueProcess.js</displayValueProcess>
</entityField>
The result is valid, but may look like an unintended change. The log contains a message similar to Linked file cleanup: AOD reference omitted because no file is present [...].
Cause
In the example above, the CAR field contains valueProcess.js, but not displayValueProcess.js. Although both references are present in the AOD file, only the existing file is retained. The converter removes unresolved references to prevent invalid project configuration.
An AOD file, such as a view, is removed automatically
An AOD file may disappear during conversion if its name is not configured consistently. The file is not transferred to YAML and is removed from the AOD project when the YAML project is transferred back.
Cause
An AOD file must contain the same name in all three of the following locations:
- The folder name, for example,
entity/Car_entity. - The file name, for example,
entity/Car_entity/Car_entity.aod. - The
<name>element inside the file, for example,<name>Car_entity</name>.
The file is valid only when all three names match. The Designer cannot display files with inconsistent names.
During AOD-to-YAML conversion, files with inconsistent names are listed in the AOD CLEANUP SCHEDULED area instead of being transferred to YAML.
Figure: Log message for removed AOD files
When transferring the project from YAML to AOD, the converter removes these files from the AOD project.
Workaround
Rename the folder, file, or <name> element so that all three names match. This ensures that the Designer can display the file.
If the file is no longer needed, remove it from the project.
Linked files, such as processes, remain at their YAML location in the AOD project
After conversion to AOD, a linked process may remain at its former YAML location instead of being removed or moved to a different location.
Cause
This can occur when you remove a file that contains links to processes. For example, CARID.field.yaml links to stateProcess.js and valueProcess.js, but you delete only CARID.field.yaml and leave the process files.
It can also occur when you remove a process property from a YAML file:
General:
position: 100
Processes:
- valueProcess: ./valueProcess.js
Processes without a parent are written to the same relative location as before. For example, a process previously located at contexts/Car/entity/field/CARID/valueProcess.js is written to that location again. No additional action is required.
Data model files must include the data model name
The converter does not accept data model files whose names omit the data model name. For example, CAR/field.yaml is not supported.
Required file name
Place the CAR field in the CAR folder and name the file CAR/CAR.field.yaml.
A value appears to be removed when converting to AOD
After converting from YAML to AOD, a value such as yPos in neonDashlet might no longer be present. This can make the converted file appear to have lost a configuration value.
Cause
This behavior is intentional. The yPos property has a default value of 0, which the converter might omit when writing the AOD file. The configured data model continues to work as expected, so no action is required.
Figure: Removed value after transforming from YAML to AOD
Incorrect Initial Autocomplete for Arrays
YAML documents containing required arrays with default values may be populated incorrectly during the initial autocomplete process.
Relevant Issue: RedHat YAML: Issue #1187
Workaround
- Remove the incorrectly generated default values from the array. The array entry should only contain the key (e.g.,
key:). - Press Ctrl+Space to trigger autocomplete again.
- Select Default Value from the suggestions.
Figure: Autocomplete of Default Array Value
A file contains only General: {}
Some generated files contain only the following content:
General: {}
The file may appear incomplete, but this is expected when it does not contain any required elements. The converter creates it so that the file remains part of the project. It will be converted back to AOD correctly.
Optional change
You can leave the file unchanged. If you need to add properties, remove {} and add the required properties.
A file contains only an empty line
After an AOD file is converted to YAML, the resulting file may contain only an empty line. Deleting this file also removes the corresponding AOD file.
Cause
The required information is already defined by the schema. The empty line tells the converter which Linux or Windows line endings to use when converting that file back to AOD.
Solution
Do not delete the empty line. If you remove it, the converter applies the operating system's line endings to the resulting file. This can cause unintended changes in the commit.
Unexpected position gaps after converting an entity with extension points to YAML
Extension points do not exist in YAML projects, but the converter must preserve their position and the data models that implement them. For example, if an entity contains field FOO, an extension point, and field BAR, the converter assigns positions 100 and 300 to FOO and BAR. The extension point is stored in the metadata with position 200.
Cause
The position property also applies to extension points. Because extension points are not supported in YAML projects, the converter stores them in metadata instead of creating a YAML file for each one.
Solution
The gaps between the position values are intentional. They preserve the extension point's position when the project is converted back to AOD.
Conversion issues when opening an AOD project in the Extension Pack
Views assigned to a module context are placed under an unexpected path
When you create a view in AOD and assign it to a context that belongs to a module, the ADITO Designer creates an insert modification for a view reference that points to the context data model. The view itself is created as a separate data model.
During AOD-to-YAML conversion, the converter cannot determine which context data model the view belongs to because the node_modules directory is always excluded. As a result, the view is treated as context-free and placed under:
contexts/<ViewName>/views/<ViewName>