Show Menu
TOPICS×

Troubleshoot Adobe Experience Manager desktop app

Adobe Experience Manager (AEM) desktop app connects to a remote Experience Manager deployment's Digital Asset Management (DAM) repository. The app fetches repository information and search results on your machine, downloads and uploads files and folders, and includes capabilities to manage conflicts with AEM Assets user interface.
Read on to troubleshoot the app, learn the best practices, and find out the limitations.

Best practices

Adhere to the following best practices to prevent some common issues and troubleshooting.
  • Understand how the desktop app works : Before starting to use the application, spend a few moments knowing how the app works. Know about linking between Experience Manager web interface and desktop, repository mapping, asset caching, saving locally and uploading in background. See how it works .
  • Avoid unsupported characters in folder names : Do not use whitespaces and invalid characters when creating or uploading folders. See a list of characters at Create folders in Experience Manager Assets . Some Adobe Experience Manager use cases may be impacted by unsupported characters in the folder name.
  • Best practices to avoid conflicts : To avoid potential conflicts when collaborating on multiple assets, see avoid editing conflicts .
  • Use folder upload for large, hierarchical folders : Instead of using the Assets web interface or other methods, use Experience Manager desktop app to upload large folders. The app uploads the assets in background with logging and monitoring. See bulk upload assets .
  • Use the latest version : Use the latest app version and always check for compatibility before installing either a new app version or before upgrading to a newer Adobe Experience Manager version. See release notes .
  • Use the same drive letter : Use the same drive letter across an organization to map to the Adobe Experience Manager DAM. To see assets placed by other users, the paths must be the same. Using the same drive letter ensures a constant path to DAM assets. The assets remain placed and are not removed even if different drive letters are used by different users.
  • Mind the network : Network performance is critical to Experience Manager desktop app's performance. If you face slowed response to file transfers or bulk operations, turn off the features or apps that might cause lots of network traffic.
  • Unsupported use cases for desktop app : Do not use the app for Assets' migration (it needs planning and other tools); for heavy-duty DAM operations (like moving large folders, large uploads, finding files using advanced metadata searches); and as a sync client (design principles and usage patterns are different from in-sync clients like Microsoft OneDrive or Adobe Creative Cloud desktop sync).
  • Timeout : Currently, desktop app does not have a configurable timeout value that disconnects the connection between Experience Manager server and desktop app after a fixed time interval. When uploading large assets, if the connection gets timeout after a while, the app retries to upload the asset a few times by increasing the upload timeout. There is no recommended way to change the default timeout settings.

How to troubleshoot

To troubleshoot desktop app issues, be aware of the following information. Also, it prepares you to better convey the issues to Adobe Customer Care if you choose to seek support.

Location of log files

Experience Manager desktop app stores its log files in the following locations depending on the operating system:
On Windows: %LocalAppData%\Adobe\AssetsCompanion\Logs
On Mac: ~/Library/Logs/Adobe\ Experience\ Manager\ Desktop
When uploading many assets, if some files fail to upload, see backend.log file to identify the failed uploads.
When working with Adobe Customer Care on a support request or ticket, you can be asked to share the log files to help the Customer Care team understand the issue. Archive the entire Logs folder and share it with your Customer Care contact.

Change level of details in log files

To change the level of details in log files:
  1. Ensure the application is not running.
  2. On Windows system:
    1. Open a command window.
    2. Launch Adobe Experience Manager desktop app by running the command:
    set AEM_DESKTOP_LOG_LEVEL=DEBUG&"C:\Program Files\Adobe\Adobe Experience Manager Desktop.exe
    
    
    On Mac system:
    1. Open a terminal window.
    2. Launch Adobe Experience Manager desktop app by running the command:
    AEM_DESKTOP_LOG_LEVEL=DEBUG open /Applications/Adobe\ Experience\ Manager\ Desktop.app
    
    
The valid log levels are DEBUG, INFO, WARN, or ERROR. The verbosity of the logs is highest in DEBUG and lowest in ERROR.

Enable debug mode

To troubleshoot, you can enable the debug mode and get more information in the logs.
Valid log levels are DEBUG, INFO, WARN, or ERROR. The verbosity of the logs is highest in DEBUG and lowest in ERROR.
To use the app in debug mode on Mac:
  1. Open a terminal window or a command prompt.
  2. Launch the Experience Manager desktop app by running the following command:
    AEM_DESKTOP_LOG_LEVEL=DEBUG open /Applications/Adobe\ Experience\ Manager\ Desktop.app .
To enable debug mode on Windows:
  1. Open a command window.
  2. Launch Experience Manager desktop app by running the following command:
AEM_DESKTOP_LOG_LEVEL=DEBUG&"C:\Program Files\Adobe\Adobe Experience Manager Desktop.exe .

Clear cache

Perform the following steps:
  1. Start the application and connect an the AEM instance.
  2. Open the application's preferences by clicking the ellipses in the upper right corner and selecting Preferences.
  3. Locate the entry displaying the Current Cache Size. Click the trash icon next to this element.
To manually clear the cache, proceed with the steps below.
This is a potentially destructive operation. If there are local file changes that are not uploaded to Adobe Experience Manager, then those changes will be lost by proceeding.
The cache is cleared by deleting the application's cache directory, which is found in the application's preferences.
  1. Start the application.
  2. Open the application's preferences by selecting the ellipses in the upper right corner and selecting Preferences.
  3. Note the Cache Directory value.
    In this directory there are subdirectories named after the Encoded Adobe Experience Manager Endpoints. The names is an encoded version of the targeted Adobe Experience Manager URL. For example, if the application is targeting localhost:4502 then the directory name will be localhost_4502 .
To clear the cache, delete the desired Encoded Adobe Experience Manager Endpoint directory. Alternatively, deleting the entire directory specified in the preferences will clear the cache for all instances that have been used by the application.
Clearing Adobe Experience Manager desktop app's cache is a preliminary troubleshooting task that can resolve several issues. Clear the cache from the app preferences. See set preferences . The default location of the cache folder is:

Know the Adobe Experience Manager desktop app version

To see the version number:
  1. Start the application.
  2. Click the ellipses in the upper right corner, hover over Help, then click About.
    The version number is listed on this screen.

Cannot see placed assets

If you cannot see the assets that you or other creative professionals placed in the support files (say, INDD files), check the following:
  • Connection to the server. Flaky network connectivity can stall asset downloads.
  • File size. Large assets take longer to download and display.
  • Drive letter consistency. If you or another collaborator placed the assets while mapping the AEM DAM to a different drive letter, the placed assets do not display.
  • Permissions. To check if you have permissions to fetch the placed assets, contact your AEM administrator.

Edits to files on desktop app's user interface do not reflect in Adobe Experience Manager immediately

Adobe Experience Manager desktop app leaves it up to the user to decide when all edits to a file are complete. Depending on the size and complexity of a file, it takes significant amount of time to transfer the new version of a file back to Adobe Experience Manager. The design of the application calls for minimizing the number of times a file is transferred back and forth, instead of guessing when the file edits are complete and are uploaded automatically. It is advised that the user initiate the transfer of the file back to Adobe Experience Manager by choosing to upload a file's changes.

Issues when upgrading on macOS

Occasionally issues may occur when upgrading AEM desktop app on macOS. This is caused by legacy system folder for AEM desktop app preventing new versions of AEM desktop app to load correctly. To remedy this issue, the following folders and files can be manually removed.
Before executing the following steps, drag the Adobe Experience Manager Desktop application from the macOS Applications folder to the Trash. Then open terminal, execute the following command, and provide your password when prompted.
sudo rm -rf ~/Library/Application\ Support/com.adobe.aem.desktop
sudo rm -rf ~/Library/Preferences/com.adobe.aem.desktop.plist
sudo rm -rf ~/Library/Logs/Adobe\ Experience\ Manager\ Desktop

sudo find /var/folders -type d -name "com.adobe.aem.desktop" | xargs rm -rf
sudo find /var/folders -type d -name "com.adobe.aem.desktop.finderintegration-plugin" | xargs rm -rf

Cannot upload files

If you are using desktop app with AEM 6.5.1 or later, upgrade S3 or Azure connector to version 1.10.4 or later. It resolves file upload failure issue related to OAK-8599 . See install instructions .

Experience Manager desktop app connection issues

If you are experiencing general connectivity issues, here are some ways to get more information about what Experience Manager desktop app is doing.
Check the request log
Experience Manager desktop app logs all requests that it sends, along with each request's response code, in a dedicated log file.
  1. Open request.log in the application`s log directory to see these requests.
  2. Each line in the log represents either a request or a response. Requests will have a > character followed by the URL that was requested. Responses will have a < character followed by the response code and the URL that was requested. Requests and Response can be matched using each line's GUID.
Check requests loaded by the application's embedded browser
A majority of the application's requests are found in the request log. However, if there is no helpful information there, then it can be useful to look into the requests sent by the application's embedded browser. See the SAML section for instructions on how to view those requests.

SAML login authentication not working

If Experience Manager desktop app does not connect to your SSO-enabled (SAML) Adobe Experience Manager instance, read on this section to troubleshoot. SSO processes are varied, sometimes complex, and the application's design does its best to accommodate these types of connections. However, some setups require additional troubleshooting.
Sometimes the SAML process does not redirect back to the originally requested path, or the final redirect is to a host that is different than what is configured in Adobe Experience Manager desktop app. To verify that this is not the case:
  1. Open a web browser.
  2. Enter the URL <AEM host>/content/dam.json in the address bar.
    Replace <AEM host> with the target Adobe Experience Manager instance, for example http://localhost:4502/content/dam.json .
  3. Log in to the Adobe Experience Manager instance.
  4. When the login is complete, look at the browser's current address in the address bar. It should exactly match the URL that was initially entered.
  5. Also verify that everything before /content/dam.json matches the target Adobe Experience Manager value configured in Adobe Experience Manager desktop app's settings.
Login SAML process works correctly according to the above steps, but users are still unable to login
The window within Adobe Experience Manager desktop app that displays the login process is simply a web browser that is displaying the target Adobe Experience Manager instance's web user interface:
Ensure that the SAML process supports those browsers.
To troubleshoot further, it is possible to view the exact URLs that the browser is attempting to load. To see this information:
  1. Follow the directions for launching the application in debug mode .
  2. Reproduce the login attempt.
  3. Navigate to log directory of the application
  4. For Windows:
    1. Open "aemcompanionlog.txt".
    2. Search for messages that begin with "Login browser address changed to". These entries also contain the URL that the application loaded.
    For Mac:
    1. com.adobe.aem.desktop-nnnnnnnn-nnnnnn.log , where the n are replaced by whichever numbers are in the newest file name.
    2. Search for messages that begin with "loaded frame". These entries also contain the URL that the application loaded.
Looking at the URL sequence that is being loaded can help troubleshoot at the SAML's end to determine what is wrong.

SSL configuration issue

The libraries that AEM desktop app uses for HTTP communication utilizes strict SSL enforcement. At times, a connection may succeed using a browser but fails using AEM desktop app. To configure SSL appropriately, install the missing intermediate certificate in Apache. See How to install an Intermediate CA cert in Apache .
The libraries that AEM Desktop uses for HTTP communication utilize strict SSL enforcement. So there can be instances where SSL connections that succeed through a browser fail with Adobe Experience Manager desktop app. This is good because it encourages correct configuration of SSL and increases security, but can be frustrating when the application is unable to connect.
The recommended approach in this case is to use a tool to analyze a server's SSL certificate and identify issues so they can be corrected. There are websites that inspect a server's certificate on providing its URL.
As a temporary measure, it is possible to disable strict SSL enforcement in Adobe Experience Manager desktop app. This is not a recommended long-term solution, as it reduces security by hiding the root cause of incorrectly configured SSL. To disable strict enforcement:
  1. Use the editor of your choice to edit the application's JavaScript configuration file, which are found (by default) at the following locations (depending on the operating system):
    On Mac: /Applications/Adobe Experience Manager Desktop.app/Contents/Resources/javascript/lib-smb/config.json
    On Windows: C:\Program Files (x86)\Adobe\Adobe Experience Manager Desktop\javascript\config.json
  2. Locate the following section in the file:
    ...
    "assetRepository": {
        "options": {
    ...
    
    
  3. Modify the section by adding "strictSSL": false as follows:
    ...
    "assetRepository": {
        "options": {
            "strictSSL": false,
    ...
    
    
  4. Save the file and restart Adobe Experience Manager desktop app.

App is unresponsive

Rarely the application may become unresponsive, display just a white screen, or display an error at the bottom of the interface without any options on the interface. Try the following in the order:
  • Right click on the application interface and click Refresh .
  • Exit the application and open it again.
In both methods, the app starts at the root DAM folder.

Need additional help with Experience Manager desktop app

Create Jira ticket with the following information:
  • Use DAM - Companion App as the Component.
  • Detailed steps to reproduce the issue in Description.
  • DEBUG level logs that were captured while reproducing the issue.
  • Target AEM version.
  • Operating system version.
  • Adobe Experience Manager desktop app version. To know your app version, see finding the desktop app version .