From ca6263c887ea9298c1e1ed05a34d29ec91cb2544 Mon Sep 17 00:00:00 2001 From: Andrei Albu Date: Wed, 8 Oct 2025 14:01:08 +0300 Subject: [PATCH 1/2] docs: add troubleshooting guide for Docker.app is damaged dialog on macOS --- .../desktop/setup/install/mac-install.md | 10 +++ .../troubleshoot/_index.md | 1 + .../troubleshoot/known-issues.md | 2 + .../troubleshoot/mac-damaged-dialog.md | 71 +++++++++++++++++++ 4 files changed, 84 insertions(+) create mode 100644 content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md diff --git a/content/manuals/desktop/setup/install/mac-install.md b/content/manuals/desktop/setup/install/mac-install.md index 12196e635411..402106b13077 100644 --- a/content/manuals/desktop/setup/install/mac-install.md +++ b/content/manuals/desktop/setup/install/mac-install.md @@ -32,6 +32,16 @@ This page provides download links, system requirements, and step-by-step install *For checksums, see [Release notes](/manuals/desktop/release-notes.md).* +> **Before you install or update** +> +> • Quit tools that might call Docker in the background (e.g., **Visual Studio Code**, terminals, agent apps). +> +> • If you manage fleets or install via MDM, prefer the [**PKG installer**](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md) (more reliable, controllable). +> +> • Keep the installer volume mounted until the installation completes. +> +> If you encounter a "Docker.app is damaged" dialog, see [Fix "Docker.app is damaged" on macOS](/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md). + ## System requirements {{< tabs >}} diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md index da9e6c6d5a41..042caccb8e34 100644 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md @@ -261,3 +261,4 @@ to learn how to view the Docker Daemon logs. - View specific [troubleshoot topics](topics.md). - View information on [known issues](known-issues.md) +- [Fix "Docker.app is damaged" on macOS](mac-damaged-dialog.md) - Resolve macOS installation issues diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md index d4d6afc5638c..7c785bf6ed67 100644 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md @@ -12,6 +12,8 @@ aliases: {{< tab name="For Mac with Intel chip" >}} - The Mac Activity Monitor reports that Docker is using twice the amount of memory it's actually using. This is due to a [bug in macOS].(https://docs.google.com/document/d/17ZiQC1Tp9iH320K-uqVLyiJmk4DHJ3c4zgQetJiKYQM/edit?usp=sharing) on this. +- **"Docker.app is damaged" dialog**: If you see a "Docker.app is damaged and can't be opened" dialog during installation or updates, this is typically caused by non-atomic copy operations when other applications are using the Docker CLI. See [Fix "Docker.app is damaged" on macOS](mac-damaged-dialog.md) for resolution steps. + - Force-ejecting the `.dmg` after running `Docker.app` from it can cause the whale icon to become unresponsive, Docker tasks to show as not responding in the Activity Monitor, and for some processes to consume a large amount of CPU resources. Reboot and restart Docker to resolve these issues. diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md new file mode 100644 index 000000000000..5d15d60c5223 --- /dev/null +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md @@ -0,0 +1,71 @@ +--- +description: Fix "Docker.app is damaged and can't be opened. You should move it to the Trash" dialog on macOS +keywords: docker desktop mac, damaged app, move to trash, gatekeeper, installation issues, troubleshooting +title: Fix "Docker.app is damaged and can't be opened" on macOS +linkTitle: MacOS app damaged dialog +tags: [Troubleshooting] +weight: 15 +aliases: +- /desktop/mac/troubleshoot/damaged-dialog/ +- /desktop/troubleshoot/mac-damaged-dialog/ +--- + +## Symptoms + +macOS shows the following dialog when you try to open Docker Desktop: + +> "Docker.app is damaged and can't be opened. You should move it to the Trash." + +This error prevents Docker Desktop from launching and can occur during installation or after updates. + +## Common causes + +This issue can typically occur due to a **non-atomic copy during a drag/drop installation**: When you drag and drop Docker.app from a DMG file while another application (like VS Code, terminals, or agent apps) is invoking the Docker CLI through symlinks, the copy operation may be interrupted, leaving the app in a partially copied state that Gatekeeper marks as "damaged." + +## Quick recovery + +Follow these steps to resolve the issue: + +### 1. Quit third-party software + +Close any applications that might call Docker in the background: +- Visual Studio Code and other IDEs +- Terminal applications +- Agent apps or development tools +- Any scripts or processes that use the Docker CLI + +### 2. Remove any partial installation + +1. Move `/Applications/Docker.app` to Trash and empty Trash. +2. If you used a DMG installer, eject and re-mount the Docker DMG. + +### 3. Reinstall Docker Desktop + +Follow the instructions in the [macOS installation guide](/manuals/desktop/setup/install/mac-install.md) to reinstall Docker Desktop. + +## If the dialog persists + +If you continue to see the "damaged" dialog after following the recovery steps: + +1. **Gather diagnostics** using the terminal by following the instructions in [Diagnose from the terminal](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md#diagnose-from-the-terminal). + - Note down the your diagnostics ID displayed in the terminal after running diagnostics. + +2. **Get help**: + - If you have a paid Docker subscription, [contact support](/manuals/desktop/troubleshoot-and-support/support.md) and include your diagnostics ID + - For community users, [open an issue on GitHub](https://github.com/docker/for-mac/issues) and include your diagnostics ID + +## Prevention + +To avoid this issue in the future: + +- If your organization allows, update Docker Desktop via the in-app update flow +- Always quit applications that use Docker before installing Docker Desktop via the DMG installer drag-and-drop approach +- In managed environments, prefer PKG installations over DMG drag-and-drop +- Keep installer volumes mounted until installation is complete + +## Related information + +- [Install Docker Desktop on Mac](/manuals/desktop/setup/install/mac-install.md) +- [PKG installer documentation](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md) +- [Troubleshoot Docker Desktop](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md) +- [Known issues](/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md) From 23866e769004ee0343b54c11bc224a55a79df5cd Mon Sep 17 00:00:00 2001 From: aevesdocker Date: Thu, 9 Oct 2025 11:10:14 +0100 Subject: [PATCH 2/2] light edit --- .../desktop/setup/install/mac-install.md | 20 ++++++------ .../troubleshoot/known-issues.md | 2 +- .../troubleshoot/mac-damaged-dialog.md | 31 +++++++++---------- 3 files changed, 26 insertions(+), 27 deletions(-) diff --git a/content/manuals/desktop/setup/install/mac-install.md b/content/manuals/desktop/setup/install/mac-install.md index 402106b13077..59462de570e5 100644 --- a/content/manuals/desktop/setup/install/mac-install.md +++ b/content/manuals/desktop/setup/install/mac-install.md @@ -32,16 +32,6 @@ This page provides download links, system requirements, and step-by-step install *For checksums, see [Release notes](/manuals/desktop/release-notes.md).* -> **Before you install or update** -> -> • Quit tools that might call Docker in the background (e.g., **Visual Studio Code**, terminals, agent apps). -> -> • If you manage fleets or install via MDM, prefer the [**PKG installer**](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md) (more reliable, controllable). -> -> • Keep the installer volume mounted until the installation completes. -> -> If you encounter a "Docker.app is damaged" dialog, see [Fix "Docker.app is damaged" on macOS](/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md). - ## System requirements {{< tabs >}} @@ -73,6 +63,16 @@ This page provides download links, system requirements, and step-by-step install {{< /tab >}} {{< /tabs >}} +> **Before you install or update** +> +> - Quit tools that might call Docker in the background (Visual Studio Code, terminals, agent apps). +> +> - If you manage fleets or install via MDM, use the [**PKG installer**](/manuals/enterprise/enterprise-deployment/pkg-install-and-configure.md). +> +> - Keep the installer volume mounted until the installation completes. +> +> If you encounter a "Docker.app is damaged" dialog, see [Fix "Docker.app is damaged" on macOS](/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md). + ## Install and run Docker Desktop on Mac > [!TIP] diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md index 7c785bf6ed67..eae248f8f60d 100644 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/known-issues.md @@ -3,7 +3,7 @@ description: Find known issues for Docker Desktop keywords: mac, troubleshooting, known issues, Docker Desktop title: Known issues tags: [ Troubleshooting ] -weight: 30 +weight: 20 aliases: - /desktop/troubleshoot/known-issues/ --- diff --git a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md index 5d15d60c5223..2efd3e04b2e1 100644 --- a/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md +++ b/content/manuals/desktop/troubleshoot-and-support/troubleshoot/mac-damaged-dialog.md @@ -4,29 +4,28 @@ keywords: docker desktop mac, damaged app, move to trash, gatekeeper, installati title: Fix "Docker.app is damaged and can't be opened" on macOS linkTitle: MacOS app damaged dialog tags: [Troubleshooting] -weight: 15 -aliases: -- /desktop/mac/troubleshoot/damaged-dialog/ -- /desktop/troubleshoot/mac-damaged-dialog/ +weight: 30 --- -## Symptoms +## Error message macOS shows the following dialog when you try to open Docker Desktop: -> "Docker.app is damaged and can't be opened. You should move it to the Trash." +```text +Docker.app is damaged and can't be opened. You should move it to the Trash. +``` This error prevents Docker Desktop from launching and can occur during installation or after updates. -## Common causes +## Possible cause -This issue can typically occur due to a **non-atomic copy during a drag/drop installation**: When you drag and drop Docker.app from a DMG file while another application (like VS Code, terminals, or agent apps) is invoking the Docker CLI through symlinks, the copy operation may be interrupted, leaving the app in a partially copied state that Gatekeeper marks as "damaged." +This issue occurs due to a non-atomic copy during a drag/drop installation. When you drag and drop `Docker.app` from a DMG file while another application, like VS Code, is invoking the Docker CLI through symlinks, the copy operation may be interrupted, leaving the app in a partially copied state that Gatekeeper marks as "damaged". -## Quick recovery +## Solution Follow these steps to resolve the issue: -### 1. Quit third-party software +### Step one: Quit third-party software Close any applications that might call Docker in the background: - Visual Studio Code and other IDEs @@ -34,23 +33,23 @@ Close any applications that might call Docker in the background: - Agent apps or development tools - Any scripts or processes that use the Docker CLI -### 2. Remove any partial installation +### Step two: Remove any partial installation 1. Move `/Applications/Docker.app` to Trash and empty Trash. 2. If you used a DMG installer, eject and re-mount the Docker DMG. -### 3. Reinstall Docker Desktop +### Step three: Reinstall Docker Desktop Follow the instructions in the [macOS installation guide](/manuals/desktop/setup/install/mac-install.md) to reinstall Docker Desktop. -## If the dialog persists +### If the dialog persists If you continue to see the "damaged" dialog after following the recovery steps: -1. **Gather diagnostics** using the terminal by following the instructions in [Diagnose from the terminal](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md#diagnose-from-the-terminal). +1. Gather diagnostics using the terminal. Follow the instructions in [Diagnose from the terminal](/manuals/desktop/troubleshoot-and-support/troubleshoot/_index.md#diagnose-from-the-terminal). - Note down the your diagnostics ID displayed in the terminal after running diagnostics. -2. **Get help**: +2. Get help: - If you have a paid Docker subscription, [contact support](/manuals/desktop/troubleshoot-and-support/support.md) and include your diagnostics ID - For community users, [open an issue on GitHub](https://github.com/docker/for-mac/issues) and include your diagnostics ID @@ -60,7 +59,7 @@ To avoid this issue in the future: - If your organization allows, update Docker Desktop via the in-app update flow - Always quit applications that use Docker before installing Docker Desktop via the DMG installer drag-and-drop approach -- In managed environments, prefer PKG installations over DMG drag-and-drop +- In managed environments, use PKG installations over DMG drag-and-drop - Keep installer volumes mounted until installation is complete ## Related information