Questions and troubleshooting
Start with the symptom, preserve your data and find the next step.
Save your work and note the state and error AppPorts displays. For missing data or interrupted migration, preserve the original drive and existing copies before following the relevant checks.
App will not open or quits immediately
Check that the original drive is online and the local entry is not an Orphaned Link. For Signature replaced, or a problem that began after upgrading to macOS 27, follow upgrades and repair. Otherwise check whether the original app supports the OS and retain error details. Not every launch failure is caused by signing.
App opens but existing data is missing
Quit the app to avoid writing into a newly created empty directory. In AppPorts, check for Mounted or a working link, then check the original app's Removable Volumes permission. Files existing externally does not establish that the app is connected to them. If both locations contain new content, preserve both, report the path types and states, and do not overwrite either.
External drive not connected or Orphaned Link
Reconnect the original drive, check Finder or Disk Utility, unlock it if needed, and refresh AppPorts. If the volume is online but Pending Mount, choose Mount. These states may indicate temporary disconnection. If the original drive and destination are confirmed but the issue persists, export diagnostics.
Mount migration checks fail
Check permissions, connectivity, format and encryption under Readiness. Installation location and operation-specific space are checked when starting migration. Container mount migration currently requires APFS; do not apply that requirement to all other content. Choose another destination or keep data local. See storage preparation.
After migrating, an app says the data directory is not mine
Such messages come from the app's own background service — for example clash-verge's system service refusing to start the kernel (error 1012). The usual cause is not lost permissions but a target disk that does not record file ownership: exFAT and FAT32 have no ownership field, and HFS+ mounted with ownership ignored writes new files as a placeholder user. Your account sees itself; the administrator service sees that placeholder, so the two disagree.
The message often suggests sudo chown, but on such volumes the system silently drops the change — it looks successful while changing nothing. What works: restore this data locally, or move it to an APFS disk (APFS keeps the real owner); for HFS+ you can untick “Ignore ownership on this volume” in Finder's Show Info and migrate again. exFAT has no such switch. See Does the external drive remember file owners?.
Destination exists, a copy is retained, or cleanup is incomplete
Identify the contents on both sides. Target Conflict needs an ownership check; Retained Copy or failed cleanup may mean the main operation succeeded but cleanup remains. Follow the retry or retain options. Do not repeat migration, manually delete recovery copies or overwrite same-named directories. See restoration and reconnection for the distinction between repairing an entry and moving data back.
Should I restart an interrupted migration?
Keep the original storage connected and inspect AppPorts' recovery instructions. Interruption can occur during copying, switching or cleanup, with different valid copies remaining at each stage. Preserve the temporary directories and backups identified by the app. If uncertain, record the last step and error rather than choosing a copy to delete yourself.
What is unsuitable for migration?
System apps, protected container structures, the entire home folder and overlapping managed directories have additional restrictions. Virtual machines, databases and downloading game libraries may have background writers; stop their use completely first. Detecting a directory does not establish that its app supports arbitrary external storage. Prefer an app's own storage-location setting when appropriate.
Why are some container directories protected?
Some directories maintain system structure, such as the container root and specific temporary directories. Changing them can prevent launch even when copying and mounting succeed. Respect protection messages; see container structure experiments for the evidence.
How do I update a moved app?
Look for Locked Migration or Unlocked Migration. Protected apps may need to move back, update and move out again. App Store-managed external installations have their own process. Follow application updates, without deleting the external copy just to get an update through.
Why does Disk Utility show extra AppPorts volumes?
They may be dedicated mount-migration data volumes. They may not remain visible in Finder's sidebar, but hold real data. To undo migration, use Restore in AppPorts rather than erasing or deleting the volumes in Disk Utility.
Can I delete AppPorts Backups?
This folder holds official app originals saved before manual re-signing, not message or document backups. If you no longer need an original and no operation is pending, you may delete that package in Finder. The installed app and personal data remain, but restoring official status may then need an official installer. AppPorts also removes originals proven redundant; see retention and cleanup.
If recovery cannot find an original, connect its drive and verify that the folder is still in place. New originals are external even when the app remains internal. Without suitable external storage, re-signing a new official original stops before changing the installed app.
Before removing AppPorts
Restore container data it still manages and confirm cleanup. Removing the program alone does not return data locally and may leave automatic reconnection without its executable. Check moved apps and ordinary data using the restoration guide too, and establish where they are stored.
Does AppPorts upload my files automatically?
Migration runs locally. Logs and diagnostic packages are also stored locally first. Update checks and sponsor-list loading use the network, so the app is not entirely offline. See the privacy policy for information and recipients.
Report a problem
In GitHub Issues, describe AppPorts and macOS versions, drive format, the operation, the complete error message and reproducibility. Use Logs → Export Diagnostic Package to obtain records. Check for private paths or content before sharing. Packages are not uploaded automatically; do not publish messages, account details or unrelated files.
Automatic mounting stops after ejection
An explicit eject request from AppPorts pauses automatic mounting for the entire disk. Even if Finder's ejection is cancelled, unplug and reconnect the device to resume. If volumes remain mounted, quit apps using them and choose Retry Eject instead of pulling the cable. See disk ejection.
A task is paused, cancelling or needs attention
Pause waits for a safe checkpoint; cancellation waits for safe cleanup. Keep the drive connected. Run in Background only closes details; return through Task Center in the toolbar. For a task needing attention, open Resolve Issues, keep the copies identified and follow recovery. Historical tasks do not automatically repeat migration after restart, and completed background cleanup does not prove the original migration succeeded.
Launching says app data is being migrated
An updated native launcher asks you to wait while associated data is migrating, being restored or paused during copying. Check the task in AppPorts and wait for completion. Protection cannot stop other routes such as opening the real app directly. Do not bypass the warning; see launch protection for its scope.