Entity Set Sync Troubleshooting with Error Logs
If the entity set sync fails, it will present an error message showing the sync stage (import, export, creating entity set, and so on) where the error occurred; and if it stopped due to a particular entity, the error will provide the entity name, the object type, and the operation name.
However the error messages may be inadequate to troubleshoot the real cause of the error. This could be because:
- The message does not have enough information. For example, if another non-sync issue leads to unexpected behavior it will not be reported on the message. The message is often not informative enough to provide a deep analysis of a sync failure.
- Another sync issue that occurred earlier in the process may be the root cause of its failure down the line. The sync engine will attempt to continue the process if it believes that it can finish correctly and provide a detailed sync result report, but sometimes this can lead to delayed errors that stop the sync process.
In these cases the administrator should investigate the server logs for a better idea of the cause of failure.
To avoid the errors that can arise during sync, see the Sync Preparation section here.
Entity set sync updates a set of knowledgebase objects that are selected in the sync configuration. For more information, see Entity Set Sync. The sync process is split into smaller components - Agiloft Sync Updaters - each of which updates a particular object; for example tables and fields, saved searches, and so on. The update might be prevented by an unsatisfied dependency, in which case the updater will update what it can, and return the corresponding status - "In Progress", or "Stalled" if nothing could be updated.
If any updates by other updaters are done, the updater will be invoked again because other updaters might have created or updated the necessary dependencies. The process is repeated until either:
- Everything is done
- All updaters are stalled - a transfer failure, or
- There is a critical error that stops the sync process.
Using Error Logs to Troubleshoot Sync Failure
The steps recommended below will help you troubleshoot the relevant error information or receive technical assistance.
Find the sync logs
The entity set sync logs, primarily sync.log, can be found at
In some cases sync issues can be found by other
Agiloft activities, so it could be helpful to use the server.log files at
Sync is sensitive to concurrent database level operations. Please avoid running a KB import/export/deletion or concurrent syncs on the same server while attempting to import an entity set.
If you want to search through the log history, use the date/timestamped files (
Locate the Error
Find the log entry with the error message that was shown in the sync result message - by text searches or timestamp - and check the log entries just above this message. You can often find helpful information here, including:
- The full stack trace of an exception.
Information relating to what the sync was trying to do at the moment of failure:
If this information is still not enough, you can try to review the logs further.
- If the log entries do not have any specific information on what caused the issue, it is recommended to check the server.log entries at the same time for any other critical errors not related directly to the sync process.
If the server log entries have information about an entity, it is recommended to check the sync log entries for occurrences of errors by the UUID or name of the entity. It is possible that some other error occurred earlier which is the real cause of the issue. For more information see UUID Recognition and Sync Conflicts.
Server logs contain entries with different levels of priority (debug, info, warn, or errors). In most cases, you should look at the log entries with WARN/ERROR priority levels.
If you need further technical assistance, you can contact the Agiloft support team by submitting a ticket with the attached sync.log and server.log files: Get Support.
Useful Unix commands for log files
grep -e "text_to_search" sync.log*- returns all sync.log.* files that contain the text_to_search.
vi sync.log- opens the sync.log file for viewing.
tail -nXX sync.log- displays the last XX lines of the file.