Troubleshooting Synchronization Errors¶
Introduction¶
The Offline OData client may occasionally encounter various synchronization errors, potentially caused by numerous factors, such as an OData back-end malfunction, a service exception, client-related faults, network disruptions, among others. For efficient resolution of these errors, gaining a sound understanding of the error message structure is beneficial.
In general, each error communication from Offline OData consists of an error code, succeeded by a summary of the error. This information enables the user to understand which component is the original source of the error and accurately identify the primary cause of this particular component's issue.
The error details from any lower-level components follow the Offline OData error details in the error message. The lower-level component may also possess its unique error code and corresponding error messages. The root cause of the synchronization error can be discerned from these lower-level component's error details.
This kind of layered error message presentation facilitates precise error tracing and ensures effective problem resolution.
Tip
See the General Recommendations for how to get the product support.
Case Studies¶
Server Synchronization Error Cases¶
Case 1¶
Error message: [-10340] The download failed due to an error on the server: -857 (SERVER_SYNCHRONIZATION_ERROR) ([-10225] Message: User exception: [-100025] An error occurred while communicating with the OData server to retrieve the result of request "$metadata". Error caused by: [-100016] Retrieve metadata failed because the OData server returned HTTP code, <code>, with OData error message:
Error analysis: Here, -10340 represents the offline OData client error code. This code indicates that the client determined that the error originated from the server side. The error code -857 is reported by the synchronization server. Meanwhile, -10225 denotes the error detail, signifying that the error surfaces while fetching the metadata from the backend. The OData backend rejected the request by responding with an HTTP status code, such as 401 or 403. As the client error message appears truncated, consider the error message from the server side to expedite diagnosis.
Case 2¶
Error message: [-10340] The download failed due to an error on the server: -857 (SERVER_SYNCHRONIZATION_ERROR) ([-10225] Message: User exception: [-100036] Failed to build the Offline OData client database.)
Error analysis: Here, -10340 is the offline OData client error code. It shows that the client has identified the error as originating from the server side. The -10225 error detail indicates the server's inability to construct the offline OData client database for downloading. If the error message does not contain sufficient details of the root failure cause, enable event logging for the service's offline component in the mobile services cockpit to capture more in-depth error messages.
Case 3¶
This is a common case of synchronization failure caused by the OAuth access token expiring during synchronization. You might see one of the following error messages:
[-10340] The download failed due to an error on the server: -857 (SERVER_SYNCHRONIZATION_ERROR) ([-10225] Message: User exception: [-100025] An error occurred while communicating with the OData server to retrieve the result of request "$metadata". Error caused by: [-100010] Retrieve metadata failed because the OData server returned HTTP code, 401, with message:
[-10340] The download failed due to an error on the server: -857 (SERVER_SYNCHRONIZATION_ERROR) ([-10225] Message: User exception: [-100027] An error occurred while processing request "Request" (url). Error caused by: [-100029] Retrieve feed "url" failed because the OData server returned HTTP code, 401, with message:
[-10340] The upload failed due to an error on the server: -857 (SERVER_SYNCHRONIZATION_ERROR) ([-10225] Message: User exception: [-100117] The upload operation failed because a request received a 401 Unauthorized status code. The session needs to be re-established to continue.
To prevent such failures from happening, application developers can choose to refresh the OAuth token before a time-consuming synchronization. See Keep OAuth Token Valid During Synchronization.
Communication Error Cases¶
Case 4¶
Error message: [-10347] The upload failed. Reason: -1305 (MOBILINK_COMMUNICATIONS_ERROR) error 63 () (system code 101)
Error analysis: For this case, -10347 denotes the offline OData client error, indicating the upload operation's failure. Error code -1305 is the underlying SQL Anywhere error code, revealing that this is a MobiLink
communication issue. The underlying error code for the MobiLink
communication error is 63, signifies it was unable to establish a socket connection. The system code 101 is platform dependent. On Android devices built on top of Linux, the error code 101 implies the network is unreachable.
Case 5¶
Error message: [-10347] The download failed. Reason: -1305 (MOBILINK_COMMUNICATIONS_ERROR) error 53 () (system code 336151568)
Error analysis: For this instance, -10347 is the Offline OData client error signaling that the upload operation failed. Error code -1305 is the underlying SQL Anywhere error code, suggesting a MobiLink
communication issue. The underlying error code for the MobiLink
communication error, 53, shows that the SSL handshake failed when attempting to establish a server connection.
Case 6¶
Error message: [-10349] The upload operation couldn't complete successfully after three attempts. The last error received was: -1305 (MOBILINK COMMUNICATIONS_ERROR), error 313 (The operation couldn't be completed. Network is down) (system code 50)
Error analysis: Here, -10349 is the Offline OData client error indicating the upload operation failed after three automatic retry attempts. The error code -1305 is the underlying SQL Anywhere error code, suggesting a MobiLink
communication issue. The underlying error code for the MobiLink
communication error, 313, reveals a network I/O failure. On iOS, which is related to the Unix OS, the system code 50 indicates that the socket operation experienced a network connectivity issue.
Case 7¶
Error message : [-10346] The download failed to establish a socket connection to the server.
Error analysis: Here, -10346 is the Offline OData client error code that conveys the client's inability to establish a socket connection to the server. It is advised to inspect firewall or proxy settings when encountering such errors.
Database Error Cases¶
Case 8¶
Error message: [-10104] An error occurred while committing a database transaction. Reason: -194 (INVALID_FOREIGN_KEY)(CHANGE_FKEY,LODATA_SYS_REQUEST_CHANGE_PARAM)
Error analysis: This error code, -10104, points to a problem that occurs during a database transaction process. Refer to the SAP Note for possible solutions when such issues arise.
Case 9¶
Error message : [-10001] An error occurred executing SQL statement: UPDATE “TableX" SET Iodata_sys_copy = IF (? & 6) < 0 THEN ? ELSE IF (? = 0x00 ) THEN OXO0 ELSE "Iodata_sys_copy* | 0x08 ENDIF ENDIF,lodata_sys_etag=?, "prop1" = ?, "prop2" =? WHERE lodata_sys_copy I= 0x01 AND lodata_sys_active = 1 AND lodata_sys_entity_id = ?. Reason: -1107 (TOO_MANY BLOB _REFS).
Error analysis: The error code -10001 signals an issue that occurred while executing an SQL statement with the underlying root cause being the -1107 TOO_MANY_BLOB_REFS error. This error communicates that the UltraLite limit of a maximum of 256 references to a particular BLOB has been reached. If an OData entity instance is updated more than 256 times locally without upload and download in the client application, the client app would encounter an error during the subsequent upload. A workaround for the hard limit of the UltraLite database would be to upload and download before reaching the limit.
Further Debugging Tips¶
For an in-depth understanding of synchronization issue that is not covered in the above cases, activate the debug log for the client app and the event log for the Offline OData component in the mobile services cockpit to obtain a more detailed context of the error. Refer to the unique error codes in the Offline OData error list and documentation to identify what each code corresponds to. Also, keep the SAP Notes and Knowledge Base Articles as a pertinent point of reference and search for the error keyword when required. In cases where the client error message appears truncated, consider the error message from the server side to expedite diagnosis.
Further readings:
SQL Anywhere Error Messages Sorted by SQLCODE
MobiLink
Communication Error Messages Sorted by Error Code