--- schema_version: "1" id: 8d0e0ef3c3f69e3a305b166a212eb40255127a639ecf51f7d2c9c45fb3f0a628 title: Troubleshooting SAP Connector 5.9 collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/sap-connector/latest/sap-connector-troubleshooting.md canonical_url: https://docs.mulesoft.com/sap-connector/latest/sap-connector-troubleshooting source_site: docs.mulesoft.com content_type: documentation content_hash: 70badd4c1af29a2fae95730e5946a9ce0fe18d942b9867de4ce52dc072eceb9c description: MuleSoft Documentation Site release: "5.9" latest: true --- --- product: SAP Connector version: 5.9 is-latest-version: true --- # Troubleshooting SAP Connector 5.9 > For the full documentation index, see: https://docs.mulesoft.com/llms.txt To troubleshoot Anypoint Connector for SAP (SAP Connector), become familiar with the information about performing general troubleshooting, addressing specific common errors, and interpreting commonly thrown exception messages. ## Enable Verbose Exception Logging Enable verbose exception logs to show a complete stack trace of the error instead of the default truncated output: 1. In Studio, right-click on the project and select **Run > Run Configurations**. 2. Go to the **Arguments** tab and append the arguments in the **VM arguments** section to add the `mule.verbose.exceptions` property. For example: `-XX:PermSize=128M -XX:MaxPermSize=256M -Dmule.verbose.exceptions=true` ## Enable Verbose Logging To get a better understanding of why an application’s interaction with SAP Connector is failing, temporarily enable verbose logging for the connector. Remember to always disable enhanced verbosity after troubleshooting, because it can affect your Mule application’s performance. To enable verbose logging in the configuration file: 1. Access Anypoint Studio and navigate to the **Package Explorer** view. 2. Open your application’s project name. 3. Open the `src/main/resources` folder. 4. Open the `log4j2.xml` file inside the folder. 5. Add an `` tag inside the `` tag: ```xml ... ... ``` 6. Save your application changes. 7. Click the project name in **Package Explorer** and then click **Run** > **Run As** > **Mule Application**. ## Perform General Troubleshooting Here is a list of general troubleshooting guidelines for SAP Connector: - [Check Log Files](#check-log-files) - [Enable JCo Trace](#enable-jco-trace) ### Check Log Files Mule stores log files (on a per-application basis) in the `$MULE_HOME\logs` directory: - `mule.log` Default Mule log file - `mule-app-YOUR_APP_NAME.log` Per-application log file ### Enable JCo Trace You can enable JCo trace externally from Mule. JCo trace accepts the following Java startup environment properties: - `-Djco.trace_level=N` Where `0` <= `N` <= `10`, and `10` is the most detailed trace - `-Djco.trace_path=` Optional JCo supports trace levels from `0` (default) through `10`. The amount of traced data increases with higher trace levels. Each trace level also contains all the trace data from the lower trace levels. If you are using a high JCo trace level with many JCo calls and transferred content, ensure that enough disk space is available. To enable traces at the connector level: 1. Set the attribute `jcoTrace` to `true` or provide the extended JCo property `jco.client.trace` or `jco.server.trace` with the value `1`. 2. Provide a value for `-Djco.trace_level=N` at Mule startup:
Trace LevelAS Java Severity LevelJCo 3 Trace Content

0

NONE

No trace

1

ERROR

JCo version and runtime environment information and JCo internal errors and exceptions without application errors

2

WARNING

JCo warning messages, for example, non-ABAP system exceptions

3

INFO

JCo information messages, for example, ABAP exceptions

4

PATH

RFC calls and important public API calls

5

DEBUG

Important internal middleware calls
Codepage information

6

DEBUG

Connection attributes
ASCII content data (the first 1000 chars of structures or the first 5 rows of tables)

7

DEBUG

RFC metadata, which includes: name, type, offset, length, import and export options, and additional hexadecimal values for content data

8

DEBUG

Full content data dump (no character or row limits)
Caller stack trace information, for example, getClient() identifies the application

9

DEBUG

No additional information (reserved for future use)

10

DEBUG

No additional information (reserved for future use)

3. Optionally, provide a value for `-Djco.trace_path=`. This is usually the complete path to an existing directory in which the trace files are stored, but you can apply other special values: - `stdout` JCo trace information is sent to standard the **output** stream - `stderr` JCo trace information is sent to standard the **error** stream If `-Djco.trace_path` is not set, then trace files are stored in the working directory. For Mule standalone instances, this is usually the `$MULE_HOME/bin` folder. ## Troubleshoot Common Errors Here is a list of the common SAP Connector errors and how to resolve them: - [Missing JCo Libraries](#missing-jco-libraries) - [JCo Classloader Conflicts](#jco-classloader-conflicts) - [JCo Version Conflicts](#jco-version-conflicts) - [JCo Renaming Conflicts](#jco-renaming-conflicts) - [Message Not an SAP Object](#message-not-an-sap-object) - [IDoc Metadata Unavailable](#idoc-metadata-unavailable) - [Missing TID Handler](#missing-tid-handler) - [Parameter Not Supported](#parameter-not-supported) - [Multiple JCo Servers Running](#multiple-jco-servers-running) ### Missing JCo Libraries These errors typically occur when you test the connection or try to deploy the Mule application without loading one or more of the required SAP JCo dependencies: - Missing JCo native library ```text java.lang.ExceptionInInitializerError: JCo initialization failed with java.lang.UnsatisfiedLinkError: no sapjco3 in java.library.path ``` - Missing JCo JAR java.lang.NoClassDefFoundError: com/sap/conn/jco/JCoTraceListener - Missing IDoc JAR java.lang.NoClassDefFoundError: com/sap/conn/idoc/IDocMetaDataUnavailableException ![Global element properties window with missing libraries](/mulesoft/current/en-us/sap-connector/latest/_images/sap-connector-missing-libraries.png) To resolve this error: 1. Click **Configure** next to the dependency with the red exclamation mark icon in the **Required Libraries** section. 2. Browse through the dependencies and select the appropriate file. The missing dependencies are automatically added to the project’s classpath. > [!TIP] In **Package Explorer**, right-click the project and navigate to **Build Path > Configure > Build Path** to view the libraries in the project’s build path. ### JCo Classloader Conflicts When you load the native library from the global configuration, a copy of the file is placed in `$YOUR_APP/src/main/app/lib`, but the source file is not removed; hence, you get the following error if the native library shares the same directory as the JCo JAR files when testing the connection or deploying your app: ```text java.lang.ExceptionInInitializerError: JCo initialization failed with java.lang.UnsatisfiedLinkError: Native Library /home/mule/sap-errors/lib/jco/libsapjco3.so already loaded in another classloader ``` ![SAP Error JCo classloader folder structure](/mulesoft/current/en-us/sap-connector/latest/_images/sap-error-jco-classloader-folder.png) To resolve this error: Choose either of the following solutions. The first is the simplest, but the second is the best practice approach. - Remove the _duplicate_ native library file from the directory in which your JCo JAR files reside: ![SAP Error JCo classloader fixed folder structure](/mulesoft/current/en-us/sap-connector/latest/_images/sap-error-jco-classloader-fix.png) - Configure the environment variable `LD_LIBRARY_PATH` to hold the dynamic link library and share it across multiple applications deployed within the same Mule runtime server. ### JCo Version Conflicts The most frequent cause of the following error is that different versions of the native library and JCo JAR files are being used: ```text java.lang.ExceptionInInitializerError: Native library sapjco3 is too old. Found library System-defined path to libsapjco3.so has version "720.612", but required is at least version "720.713". ``` To resolve this error, ensure that the following requirements are met: - 64-bit JCo is required on a JVM that runs in 64-bit mode, and 32-bit JCo is required on a JVM that runs in 32-bit mode. - On Microsoft Windows, JCo requires the Microsoft Visual Studio 2005 C/C++ runtime libraries. - Both the `sapjco.jar`, and one of `sapjco3.dll` or `sapjco3.so` or `sapjco3.jnilib` must be from the **same JCo package**. To verify the versions of the JCo libraries that you are using, do one of the following: - On Windows (in the UI): 1. Navigate to the directory in which the `sapjco3.jar` file is located. 2. Right-click the `sapjco3.jar` file. 3. Select **Open With** from the context menu. 4. Click the **Java 2 Platform Standard Edition** binary. 5. Verify the information shown in the JCo dialog that displays. - On Mac: 1. Open a terminal window. 2. Navigate to the directory in which the `sapjco3.jar` file is located. 3. Execute the command `java -jar sapjco3.jar -version`. 4. Verify the information shown in the JCo dialog that displays. ### JCo Renaming Conflicts You cannot rename any of the SAP JCo library files in JCo 3.0.11 or later as they won’t be recognized by JCo, and you receive the following error: ```text java.lang.ExceptionInInitializerError: Illegal JCo archive "sapjco3-3.0.11.jar". It is not allowed to rename or repackage the original archive "sapjco3.jar" ``` This is also true for the IDoc library and you might receive this error: ```text java.lang.ExceptionInInitializerError: Illegal IDoc library archive "sapidoc3-3.1.4.jar". It is not allowed to rename or repackage the original archive "sapidoc3.jar". ``` To resolve this error, add this `maven-shade-plugin` to your application’s `pom.xml` file: ```xml org.apache.maven.plugins maven-shade-plugin 3.5.1 package shade false sapjco3-group-id:sapjco3-artifact-id sapidoc3-group-id:sapidco3-artifact-id ``` > [!NOTE] To prevent build issues, ensure the versions of `maven-shade-plugin` and > `munit-maven-plugin` are compatible: > > - `maven-shade-plugin` 3.5.x and later requires `munit-maven-plugin` 2.3.x and later. > > - `maven-shade-plugin` 3.4.x and earlier requires `munit-maven-plugin` 2.2.x and earlier. To determine the correct `groupId` and `artifactId` values, refer to your existing dependencies. An example configuration is shown below (these might vary depending on your setup): ```xml com.sap.conn.jco com.sap.conn.jco.sapjco3 3.1.12 com.sap.conn.idoc com.sap.conn.idoc.sapidoc3 3.1.4 ``` In this example, the full artifact coordinates are `com.sap.conn.jco:com.sap.conn.jco.sapjco3` and `com.sap.conn.idoc:com.sap.conn.idoc.sapidoc3`. > [!NOTE] Shading might increase the application size by nearly 2 MB. ### Message Not an SAP Object The endpoint expects an SAP object with the input parameters that are necessary to execute a BAPI or an IDoc. If you receive the following message, either: - The necessary input parameters are not provided. - The input parameters are provided but the SAP object is malformed. ```text org.mule.api.transport.DispatchException: Message is not a SAP object, it is of type "byte[]". Check the transformer for this Connector "SapConnector". Failed to route event via endpoint: SapOutboundEndpoint{endpointUri=sap://function, connector=SapConnector { name=SapConnector lifecycle=start this=4571cebe numberOfConcurrentTransactedReceivers=4 createMultipleTransactedReceivers=true connected=true supportedProtocols=[sap] serviceOverrides= } , name='endpoint.sap.function', mep=ONE_WAY, properties={evaluateFunctionResponse=false, bapiTransaction=false, functionName=BAPI_MATERIAL_AVAILABILITY, rfcType=srfc, outputXml=true}, transactionConfig=Transaction{factory=null, action=INDIFFERENT, timeout=0}, deleteUnacceptedMessages=false, initialState=started, responseTimeout=10000, endpointEncoding=UTF-8, disableTransportTransformer=false}. Message payload is of type: byte[] ``` To resolve this error: Create an SAP object that represents the call to the BAPI or IDoc by performing one of the following two actions: - Create XML that contains an SAP object with the BAPI call. - Provide an XML definition that includes input to create the actual SAP call. ### IDoc Metadata Unavailable When you receive the following error, it means that the RFC destination does not support Unicode: ```text RfcException: [mc-vmware|a_rfc] message: (3) IDOC_ERROR_METADATA_UNAVAILABLE: The meta data for the IDoc type "??????????????????????????å å" with extension " ORDSAPB6L B60CL ???" is unavailable. Return code: RFC_FAILURE(1) error group: 104 key: RFC_ERROR_SYSTEM_FAILURE ``` To resolve this error: Use transaction **SM59** to configure Unicode support in your SAP instance. ### Missing TID Handler Because no TID handler is defined, you receive the following error: ```text RfcException: [mule.local|MULESOFT_IDOC_SEND_TEST] message: check TID fault: No transaction handler is installed. Unable to process tRFC/qRFC requests. Return code: RFC_FAILURE(1) error group: 104 key: RFC_ERROR_SYSTEM_FAILURE Exception raised by myhost.com.ar|MULESOFT_IDOC_SEND_TEST at com.sap.conn.jco.rt.MiddlewareJavaRfc$JavaRfcServer.playbackTRfc(MiddlewareJavaRfc.java:2625) at com.sap.conn.jco.rt.MiddlewareJavaRfc$JavaRfcServer.handletRfcRequest(MiddlewareJavaRfc.java:2546) at com.sap.conn.jco.rt.MiddlewareJavaRfc$JavaRfcServer.listen(MiddlewareJavaRfc.java:2367) at com.sap.conn.jco.rt.DefaultServerWorker.dispatch(DefaultServerWorker.java:284) at com.sap.conn.jco.rt.DefaultServerWorker.loop(DefaultServerWorker.java:369) at com.sap.conn.jco.rt.DefaultServerWorker.run(DefaultServerWorker.java:245) at java.lang.Thread.run(Thread.java:680) ``` To resolve this error: Set `rfcType` to `trfc` or `qrfc` in ``. ### Parameter Not Supported Because SAP extended properties must have valid names, if you provide an invalid property name, you receive an error message similar to this one: ```text Root Exception stack trace: RfcException: [null] message: Parameter 'type' not supported: 'f' Return code: RFC_INVALID_PARAMETER(19) error group: 101 key: RFC_ERROR_PROGRAM at com.sap.conn.rfc.api.RfcOptions.checkParameters(RfcOptions.java:182) at com.sap.conn.jco.rt.MiddlewareJavaRfc$JavaRfcClient.connect(MiddlewareJavaRfc.java:1328) at com.sap.conn.jco.rt.ClientConnection.connect(ClientConnection.java:731) + 3 more (set debug level logging or '-Dmule.verbose.exceptions=true' for everything) ``` In this example, JCo libraries are reporting that the parameter with name `type` is not valid. To resolve this error: Provide a valid property name from JCo extended properties. ### Multiple JCo Servers Running Two or more JCo servers cannot have the same set of configuration parameters, even if they have different configuration names, so you receive the following error: ```text ERROR 2012-07-05 10:11:30,525 [WrapperListener_start_runner] com.mulesoft.mule.transport.sap.SapMessageReceiver: Error connecting to server com.sap.conn.jco.JCoException: (101) JCO_ERROR_CONFIGURATION: Server configuration for sapavalara-1.0-SNAPSHOT-gettax is already used for a running server at com.sap.conn.jco.rt.StandaloneServerFactory.update(StandaloneServerFactory.java:358) at com.sap.conn.jco.rt.StandaloneServerFactory.getServerInstance(StandaloneServerFactory.java:176) at com.sap.conn.jco.server.JCoServerFactory.getServer(JCoServerFactory.java:74) at com.mulesoft.mule.transport.sap.jco3.SapJcoRfcServer.initialise(SapJcoRfcServer.java:46) at com.mulesoft.mule.transport.sap.jco3.SapJcoServerFactory.create(SapJcoServerFactory.java:60) at com.mulesoft.mule.transport.sap.SapMessageReceiver.doConnect(SapMessageReceiver.java:56) at org.mule.transport.AbstractTransportMessageHandler.connect(AbstractTransportMessageHandler.java:218) at org.mule.transport.AbstractConnector.registerListener(AbstractConnector.java:1254) ``` > [!NOTE] This applies only to Mule applications running on the same Mule server. Nodes on a Mule > server group do not have this limitation. To resolve this error: Use the following attributes to create the server group key (which determines the uniqueness of a JCo server connection): - `jco.server.gwhost` - `jco.server.gwserv` - `jco.server.progid` You can start two servers in the same Mule instance (JCo keeps this information in a Singleton class) only if they have different values for `gwhost`, `gwserv`, and `progid`. ## Understand Commonly Thrown Exceptions Here is a list of commonly thrown exception messages and how to interpret them: - SAP:CONNECTIVITY A connection cannot be established. - SAP:INVALID\_CACHE The cache used internally by the JCo library is corrupted or can’t be read. - SAP:INVALID\_INPUT User input cannot be parsed or is incorrect. - SAP:METADATA\_UNAVAILABLE The metadata for an IDoc segment is unavailable. - SAP:NOT\_FOUND A function or IDoc template cannot be found or retrieved. - SAP:NOT\_SUPPORTED An action occurs that is not supported by any JCo handler. - SAP:PARSING The JCo library has a parsing issue or the connector cannot convert XML to a BAPI function or an IDoc. - SAP:RETRY\_EXHAUSTED Execution block retries are exhausted. - SAP:SYSTEM\_BUSY The remote ABAP system is too busy to handle a request. - SAP:TIMEOUT A timeout exception happens inside the JCo library. ## See Also - [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors) - [SAP Connector Reference](https://docs.mulesoft.com/sap-connector/latest/sap-connector-reference) - [Salesforce Help](https://help.salesforce.com) - [Known Issues](https://help.salesforce.com/s/issues)