DocumentationAEMDesktop App Guide

Troubleshoot Adobe Experience Manager desktop app

Last update: Thu Jun 01 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • User
  • Admin

Adobe Experience Manager desktop app connects to a 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 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 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 Experience Manager version. See release notes.

  • Use the same drive letter: Use the same drive letter across an organization to map to the 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 Support 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.

NOTE
When working with Adobe Customer Support on a support request or ticket, you can be asked to share the log files to help the Customer Support team understand the issue. Archive the entire Logs folder and share it with your Customer Support 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:

    code language-shell 
    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:

    code language-shell 
    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.

NOTE
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.

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.

Clear cache

Perform the following steps:

  1. Start the application and connect an the Experience Manager 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.

CAUTION
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:

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 Experience Manager 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 Experience Manager 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 Experience Manager desktop app on macOS. This is caused by legacy system folder for Experience Manager desktop app preventing new versions of Experience Manager 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 Experience Manager 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

Experience Manager desktop app may not connect to your SSO-enabled (SAML) Adobe Experience Manager deployment. The application’s design attempts to accommodate the variations and complexities of SSO connections and processes. However, a setup may 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. Access https://[aem_server]:[port]/content/dam.json URL.

  2. Log in to the Adobe Experience Manager deployment.

  3. 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.

  4. 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:

  • The Mac version uses a WebView.

  • The Windows version uses Chromium-based CefSharp.

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 Experience Manager desktop app uses for HTTP communication utilizes strict SSL enforcement. At times, a connection may succeed using a browser but fails using Experience Manager 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 Experience Manager desktop app 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:

    code language-shell 
    ...
"assetRepository": {
    "options": {
...

  3. Modify the section by adding "strictSSL": false as follows:

    code language-shell 
    ...
"assetRepository": {
    "options": {
        "strictSSL": false,
...

  4. Save the file and restart Adobe Experience Manager desktop app.

Login issues when switching to a different server

After using an Experience Manager server, when you attempt to change the connection to a different server, you may encounter login issues. It is due to old cookies interfering with new authentication. An option in the main menu to Clear Cookies helps. Logout of the current session in the app and select Clear Cookies before proceeding to connect.

Clear cookies when switching server

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.

Hide expired assets

When browsing assets from within Experience Manager user interface, the expired assets are not displayed. To prevent viewing, searching, and fetching of expired assets when browsing assets from desktop app and Asset Link, administrators can do the following configuration. The configuration works for all users, irrespective of administrator privilege.

Related Articles
d27c3dc5-a94a-4e63-a6d5-c47555beb65d