Troubleshooting

Even the most straightforward installation process can meet unforeseen issues. This section offers comprehensive troubleshooting tips and solutions to common problems encountered during installation.

If you meet any troubleshooting, please contact us to have solution and to share your troubleshooting to this page.

1. Connection refused

If the server fails to start and displays a Connection refused error such as:

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'liquibase' defined in class path resource [org/springframework/boot/autoconfigure/liquibase/LiquibaseAutoConfiguration$LiquibaseConfiguration.class]: org.postgresql.util.PSQLException: Connection to localhost:5434 refused.

Make sure you have a clean database running without any earlier data, and start the server. You should delete your existing container docker rm syson-postgres and even the image docker rmi image-ID to ensure a fresh start.

2. Changelog not found

If the server fails to start and displays changelog.xml not found error such as:

Application run failed

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'liquibase' defined in class path resource [org/springframework/boot/autoconfigure/liquibase/LiquibaseAutoConfiguration$LiquibaseConfiguration.class]: ERROR: The file 'classpath:db/changelog/syson.db.changelog.xml' was not found.

Make sure you have included the correct argument to your java command according to your Obeo Enterprise for SysON version.

Check that you are consulting the documentation version that matches the JAR version you are trying to run.

Refer to the installation-guide:how-tos/install/production_deploy.adoc#start-app section for detailed instructions according to your version.

3. Empty page in web browser

If you encounter an empty page while accessing to Obeo Enterprise for SysON through your web browser, it might be because you have installed Obeo Enterprise for SysON on a local server or machine and want to access it from another one.

If you open the dev tools of your web browser, you may found the following message: Uncaught TypeError: crypto.randomUUID is not a function.

In this case, please refer to Configuring HTTPS for local server deployment of Obeo Enterprise for SysON for testing purposes.

4. Running docker on Mac Silicon architecture

Obeo Enterprise for SysON Docker images are multi-platform (x86_64 and arm64) starting with version v2026.9.0, so they run natively on Mac Silicon and other arm64 machines. If you need to run an older Obeo Enterprise for SysON docker image on a Mac Silicon architecture, please execute the following command in your terminal before executing the docker image:

export DOCKER_DEFAULT_PLATFORM=linux/amd64

5. Problems when not using a standard Docker environment

If your container environment is not a standard Docker installation (podman for example) you may run into access problems. These can be solved by adding

    privileged: true

to both containers (database and app) in the docker-compose.yml.

6. NetworkError when downloading a document

If you encounter a NetworkError when trying to download a document from Obeo Enterprise for SysON, don’t worry this is a known issue that will be fixed in the next releases. It does not affect the download of the document.