Troubleshoot AEM desktop app to resolve the occasional issues related to installation, upgrade, configuration, and so on.
Adobe Experience Manager desktop app includes utilities that assist you in mapping the AEM Assets repository as a network share on desktop (SMB share on Mac OS). Network share is an operating system technology that enables remote sources to be treated as if they were part of a computer’s local file system. In the case of desktop app, a remote AEM instance’s digital asset management (DAM) repository structure is targeted as the remote file source. The following diagram describes the desktop app topology:
With this architecture, desktop app intercepts file system calls (open, close, read, write, and so on) to the mounted network share, and translates them into native AEM HTTP calls to the AEM server. Files are cached locally. For more details, see Use AEM desktop app v1.x.
desktop app includes the following components:
AEM desktop app uses the network share technology to map a remote AEM repository to a local desktop. However, it is not intended as a replacement for a network share holding assets, where users perform digital asset management operations directly from their local desktop. These include moving or copying multiple files, or dragging large folder structures to the AEM Assets network share directly in Finder/Explorer.
AEM desktop app provides a convenient way of accessing (opening) and editing (saving) DAM assets between the AEM Assets Touch UI and the local desktop. It links assets in the AEM Assets server with your desktop-based workflows.
The following example use case illustrates how AEM Desktop should be used:
This is not the only use case. However, it illustrates how AEM Desktop is a convenient mechanism to access/edit assets locally. You are encouraged to use the DAM web UI as much as possible because it provides a better experience. It provides Adobe more flexibility to meet customer requirements.
WebDAV/SMB1 network share provides the convenience of working with files in an Explorer/Finder window. However, Explorer/Finder and AEM communicate over a network connection that has certain limitations. For example, the time consumed to copy a 1-GB file to the mounted WebDAV/SMB directory is approximately the same as the time required to upload a 1-GB file to a website using a web browser. In fact, in the former case, the duration may be longer due to inefficiencies of the WebDAV/SMB protocol and the OS’s WebDAV/SMB clients (particularly Mac OS X).
There are limitations to the types of tasks that can be performed from a mounted directory. In general, working with large files especially over a poor/high latency/low bandwidth network connection might be challenging, especially when editing large files.
Adobe recommends that you perform some use-case testing before committing to a client that certain types of files can be efficiently edited in-place from the mounted directory.
AEM Desktop is not suitable for performing intensive file system manipulation, including but not limited to:
Due to limitations in the operating system, Windows has a file size limitation of 4,294,967,295 bytes (approximately 4.29 GB). It is due to a registry setting that defines how large a file on a network share can be. The value of the registry setting is a DWORD with a maximum size that equals the referenced number.
Experience Manager 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.
AEM desktop app provides internal caching and background upload capabilities to improve end user experience. When you save a large file, it is first saved locally to let you continue working. After sometime (currently 30 seconds), the file is then sent to the AEM server in the background.
Unlike Creative Cloud Desktop or other file sync solutions, such Microsoft One Drive, AEM desktop app is not a full Desktop Sync client. The reason for this is that it provides access to the entire AEM Assets repository, which can be extremely large (hundreds of gigabytes or terabytes) for a full synchronization.
Caching provides the ability to limit the network/storage overhead to only a subset of assets that are relevant to the user.
Adobe recommends turning off thumbnail generation to make browsing faster. If you enable icon previews, the app caches the digital assets when you navigate through the mounted folder. The app also downloads assets that the user may not care about, which adds load to the server, consumes the user’s bandwidth, and uses more of the user’s disk space.
Here is how AEM desktop app performs caching:
Every operation is not cached locally. The following are transmitted to the AEM Server immediately without local caching:
When troubleshooting sub-optimized performance for the individual users, first review the app limitations. The subsequent sections include suggestions to improve performance for the individual users.
The bandwidth available to an individual user plays a critical role in the performance of the WebDAV/SMB client.
Adobe recommends that an individual user’s upload speed to be close to 10 Mbps. For wireless connections, bandwidth is often shared between multiple users. If multiple users simultaneously perform tasks that consume network bandwidth, the performance can degrade even further. To avoid such issues, use a wired connection.
When you interact with a file locally, AEM Desktop checks whether a newer version of the file is available in AEM. If a new version is available, the application downloads a fresh copy of the file to the local cache. However, AEM Desktop does not overwrite a locally cached file if it has been modified. This feature prevents your work from being overwritten inadvertently.
When the same file is modified both locally and in AEM, the locally modified version overwrites the version in AEM. In this case, the previous version is available in the asset’s timeline. You can verify both versions and resolve any conflicts.
If a local file is inconsistent with the version available in the server, the background upload status dialog notifies you about the conflict. To resolve the issue, open the conflicting file and save it. Saving the file forces AEM Desktop to sync your latest local changes to AEM. You can view previous versions of the asset in the timeline and resolve any conflicts.
You should take into account additional factors when multiple users attempt to work in separate mounted directories targeting the same AEM instance. In particular, the following factors are important:
If the WebDAV/SMB performance degrades drastically when multiple users work simultaneously, you can configure a few things in AEM, which can help improve performance.
You can improve the performance at the AEM side by enabling transient workflows for the DAM Update Asset workflow. Enabling transient workflows reduces the processing power required to update assets when they are created or modified in AEM.
/miscadminin the Experience Manager instance (
Another method for improving AEM performance is to configure the value of the maximum parallel jobs for the Granite Transient Workflow Queue job. The recommended value is roughly half the number of the CPU available with the server. To adjust the value, perform these steps:
/system/console/configMgrin the AEM instance to be configured (for example,
QueueConfiguration, and click to open each job until you locate the Granite Transient Workflow Queue job, and click Edit.
Maximum Parallel Jobsvalue, and click Save.
Owing to network bandwidth limitations, the performance of WebDAV/SMB may degrade when multiple users work simultaneously. Adobe recommends increasing the size of the AWS instance for a target AEM instance that runs on AWS to enhance the performance of WebDAV/SMB.
This measure specifically boosts the amount of network bandwidth available to the server. Here are some details:
There are a few known limitations in the way you can interact with checked-out files through Explorer/Finder. If a file is checked out, it should be read-only to anyone except the user that has the file checked out. The implementation of the WebDAV/SMB1 protocol in AEM enforces this rule. However, OS WebDAV/SMB clients often don’t interact gracefully with checked-out files. Some oddities are described below.
When writing to a checked-out file, the lock is only enforced within AEM WebDAV implementation. Consequently, the lock is only enforced by clients that use WebDAV, such as desktop app. The lock is not enforced through AEM web interface. The AEM interface merely displays a lock icon in the card view for assets that are checked out. The icon is cosmetic and has no effect on the behavior of AEM.
In general, the WebDAV clients don’t always behave as expected. There may be additional issues. However, refreshing or checking the asset in AEM is a sound way to verify that an asset isn’t being modified. This behavior is typical of the OS WebDAV clients, which isn’t under Adobe’s control.
Deleting a file appears to succeed because the file disappears from the file explorer in Windows. However, refreshing the directory and checking in AEM assets shows that the file is still present. In addition, editing files appears to succeed (no warning dialogs or error messages are displayed). However, reopening the file or checking in AEM assets reveals that the file is unchanged.
Replacing a file doesn’t display a warning or error, but checking the asset in AEM reveals that it remains unchanged. Refresh or check the asset in AEM to verify that it isn’t being modified.
After you install desktop app, the desktop app menu icon appears in the menu bar. If the icon doesn’t appear, perform these steps to resolve the issue:
Open the operating system terminal window.
Type the following command at the command prompt, and then press Enter:
Type the following command, and press Enter:
rm -r com.adobe.aem.assetscompanion
Type the following command, and press Enter:
Type the following command, and press Enter:
Type the following command, and press Enter:
rm ~/Library/Group\ Containers/group.com.adobe.aem.desktop/*
Restart the system.
AEM Desktop attempts to sync any given file three times. If the file fails to sync after the third attempt, AEM Desktop considers the file to be in conflict and notifies you via the background upload status window. A conflict state indicates that your latest changes are still available to you locally, but they are not synced back to AEM. AEM desktop app no longer attempts to sync.
The simplest way to fix this situation is to open the conflicting file and save it again. It forces AEM Desktop to attempt synchronization for an additional three occasions. If the file still fails to sync, see the sections below for more help.
Clearing AEM Desktop’s cache is a preliminary troubleshooting task that can resolve several AEM Desktop issues.
You can clear the cache by deleting the application’s cache directory at the following locations.
However, the location can change depending on AEM Desktop’s configured AEM endpoint. The value is an encoded version of the targeted URL. For example, if the application is targeting
http://localhost:4502, the directory name is
To clear the cache, delete the <Encoded AEM Endpoint> directory.
If you clear AEM Desktop cache, local file changes that are not synced to AEM are lost.
Starting with AEM desktop app version 1.5, there is an option in the desktop app UI to clear the cache.
The procedure to ascertain the AEM Desktop version is the same for both Windows and Mac OS.
Click the AEM Desktop icon, and then choose About. The version number is displayed on the screen.
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 to load correctly. To remedy this issue, the following folders and files can be manually removed.
Prior to executing the steps below, drag the “Adobe Experience Manager Desktop” application from the macOS Applications folder to the Trash. Then open terminal, and execute the following command, providing 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
Technical limitations of the operating system prevent users from having a consistent experience when attempting to overwrite a file that is checked out by others. The experience varies depending on the application used to edit the checked out file. Sometimes, the application displays an error message indicating a disk write failure or displays a seemingly unrelated or generic error. On other occasions, no error message is displayed and the operation appears to succeed.
In this case, closing and reopening the file may reveal that the contents are unchanged. However, some applications may store a backup of the file so your changes can be applied.
Regardless of the behavior, the file remains unchanged when you check it in. Even if a different version of the file is displayed, the changes are not synced to AEM.
The server API requires additional headers, X-Destination, X-Depth, and X-Overwrite, to be passed for the move and copy operations to work. The dispatcher does not pass these headers by default, which causes these operations to fail. For more information, see Connecting to AEM Behind a Dispatcher.
The most common reason for issues with AEM Desktop connecting to your SSO-enabled (SAML) AEM instance is that the SAML process does not redirect back to the originally requested path. Alternatively, the connection may be redirected to a host that not configured in AEM desktop. Perform these steps to verify the login process:
/content/dam.jsonmatches the target AEM value configured in AEM Desktop.
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.
AEM Desktop works with AEM deployments behind a dispatcher, which is a default and recommended configuration for AEM servers. AEM dispatchers in front of AEM authoring environments are typically configured to skip caching DAM assets. Therefore, dispatchers do not provide additional caching from the AEM Desktop standpoint. Ensure that the dispatcher configuration is adjusted to work for AEM Desktop. For additional details, see Connecting to AEM behind a dispatcher.
Depending upon your operating system, you can find the log files for AEM Desktop at the following locations:
~/Library/Logs/Adobe\ Experience\ Manager\ Desktop