Skip to main content

Celonis Product Documentation

Troubleshooting on-prem clients installation

We've gathered some resources and troubleshooting tips that will help you resolve some problems you might encounter with on-prem client installation.

Tip

For comprehensive information about your on-prem client's installation status, from your terminal, run .\opc-management-tool | echo.

The opc-management-tool.app is damaged can’t be opened (MacOS)

Symptoms

When trying to open the opc-management-tool.app on MacOS, the following error is displayed:

"opc-management-tool.app" is damaged and can't be opened. You should move it to the Bin.

Cause

The most common root cause of this issue is missing privileges.

Solution

To resolve this problem:

  1. Go to the Shared folder.

  2. Open Terminal and issue the following command:

    xattr -cr opc-management-tool.app
Request for device code authorization returns status 403 (Forbidden)

Symptoms

In the On-prem Client Management Tool, when you click Connect to Celonis Platform to request code authorization the following error is displayed:

Error: request for device code authorisation returned status 403 (Forbidden).

Cause

The error usually occurs when a VPN is required for connecting.

Solution

Enable your VPN and try again.

The installation ends with "Microsoft Edge can't read and write to it's data directory." message (Windows)

Symptoms:

The On-prem Client Management Tool returns the following error during the installation:

Microsoft Edge can't read and write to it's data directory. 
C:\Users{admin-account}\AppData\Roaming{wails-app-name}.exe\EBWebView"

Cause:

This error can occur when the opc-management-tool.exe is run using a non-admin account.

Solution:

Using a non-admin user account:

  1. Open Task Manager.

  2. In the Details tab, search for

    msedgewebview2

  3. Right-click any of the msedgewebview2.exe executables and go to its properties.

  4. In the Compatibility tab, select Run this program as an administrator.

  5. Click OK.

  6. Open the opc-management-tool.exe again.

The installation fails with the launchctl error on MacOS

Symptoms:

On MacOS, in the On-prem Client Management Tool, when you click Connect to Celonis Platform to request code authorization the error related to launchctl is displayed.

Cause:

This error can occur when the On-prem Client Management Tool is run from a folder on which MacOS has permissions restrictions like the Download folder or Desktop.

Solution:

  1. In the On-prem Client Management Tool, uninstall all deamons from the Automation Agent and SAP Extraction tabs.

  2. Close the On-prem Client Management Tool.

  3. Move the on-prem client package to the home folder and try the installation again.

The installation verification fails with the Acces denied error

Symptoms:

When trying to verify the on-prem client installation using the verification URL received from the IT Admin, Celonis Platform displays the Access denied error.

Cause:

This error occurs when the verification is done by a user with insufficient Celonis Platform rights.

Solution:

To verify the on-prem clients installation, you must be a Celonis Platform admin or you must have "edit agent" permissions assigned to your role.

"unable to find valid certification path" errors

Symptoms:

If your extractor status is "unlinked" and you see errors in your extractor log such as:

2019-09-24 23:55:27.060  INFO 25627 --- [uplink-thread-0] c.celonis.uplink.manager.UplinkManager   : Uplink could not connect: I/O error on POST request for "https://team.eu-1.celonis.cloud/uplink/api/public/uplink": PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target; nested exception is javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target --EOM--

Cause:

There are a couple of possible causes but the first one outlined below is by far the most likely:

  • Your network overrides the standard certificates with its own when communicating with Celonis Platform.

  • Your Java package may not come with the root and intermediate CA certificates necessary to communicate with the Celonis Platform over HTTPS.

Solution:

  1. Your network overrides the standard certificates with its own when communicating with Celonis Platform:

    1. Ask your IT administrators whether a proxy server overrides the certificates, and request the root CA and intermediate certificate files. Alternatively, you can access the Celonis Platform in a browser from the extractor server and export the certificates from there.

    2. Follow the instructions in the importing certificates section below to import them.

  2. Your Java package may not come with the root and intermediate CA certificates necessary to communicate with the Celonis Platform over HTTPS.

    1. Visit https://letsencrypt.org/certificates/ and download the active root certificate, as well as one of the active and backup intermediate certificates. Save them somewhere accessible by the extractor server.

    2. Follow the instructions in the importing certificates section below to import them.

Importing the certificates

From the command line on the extractor server, execute the following commands as an administrator and then restart the extractor:

keytool -v -cacerts -storepass changeit -importcert -alias cel_root.pem -file ~/path/to/root_cert_file
keytool -v -cacerts -storepass changeit -importcert -alias cel_inter.pem -file ~/path/to/intermediate_cert_file

Note

  • If the 'keytool' command cannot be found, first change directory to '/path/to/java/bin'

  • 'changeit' is java's default keystore password, please use your own if you have changed it

The service shows as "Disconnected" in Celonis Platform

Symptoms:

When consent is granted by copying the URL, the service is still shown as "Disconnected" in Celonis Platform.

The logs folder under the "Extraction Agent" folder is not created.

This can happen when the setup is done with a non-root user, but this user has executable permissions for all the files and folders created.

Cause:

The on-prem CLI tool is not able to inherit the user settings. Hence the Java home path is not correctly mapped when the service is started.

This happens even if you've configured the ~/.bashrc and ~/.bash_profile for the user by updating the PATH and  JAVA_HOME variables with the actual path where Java is installed.

To set the JAVA_HOME variable in your shell profile file (for example, .bashrc, .bash_profile, .profile, or .zshrc depending on your shell and your preferences):

  1. Add these lines to the profile file:

    export JAVA_HOME=<the path to your Java installation>
export PATH=$JAVA_HOME/bin:$PATH

    For example:

    export JAVA_HOME=/usr/lib/jvm/Java-11-openjdk
export PATH=$JAVA_HOME/bin:$PATH

  2. Apply the changes by sourcing the file. For example, if you modified .bashrc:

    source ~/.bashrc

    Or if you modified .bash_profile:

    source ~/.bash_profile

  3. Verify that the JAVA_HOME and PATH variables are set correctly:

    echo $JAVA_HOME
echo $PATH

    You should see the path to your Java installation and the updated PATH respectively.

  4. Verify the Java version to ensure everything is set up correctly:

    java -version

Solution:

There are two ways to make sure the Java environment variables are read correctly when the On-Prem CLI tool is executed.

  • Edit the /extraction-agent/start-celonis-agent.sh file and replace the java with the whole java path.

    For example, edit the file from this:

    1  #!/bin/bash
2  cd "$( dirname "$0" )"
3  java -jar -Dspring.profiles/active=celonis,local agent.jar

    to this:

    1  #!/bin/bash
2  cd "$( dirname "$0" )"
3  /usr/ec2-user/java17/zulu/bin/java -jar -Dspring.profiles/active=celonis,local agent.jar

    Then save the change and restart the agent service from the CLI tool.

  • Create a symbolic link named java in the /usr/bin directory, pointing to the actual Java binary located at /usr/ec2-user/java17/zulu/bin/java with the command:

    ln -sf /usr/ec2-user/java17/zulu/bin/java /usr/bin/java

    After you've run this command, /user/bin/java will point to the /usr/ec2-user/java17/zulu/bin/java. Invoking java from the command line will execute the Java binary located at /usr/ec2-user/java17/zulu/bin/java.

    Replace /usr/ec2-user/java17/zulu/bin/java with the path where the Java binary file is located. Then restart the agent service from the CLI tool.