Start with the status in the menu bar
Dropbox tells you what it thinks it is doing, and most people never look. Click the Dropbox icon in the menu bar. Dropbox says the sync status displays at the bottom of the window that appears.
- Indexing — your files are preparing to sync. It has not started moving them yet.
- Syncing [x] files — it is working. Leave it alone.
- Your files are up to date — Dropbox believes it has finished. If a file is still missing, the cause is that one file, not the app.
- Syncing paused until [x] — it is paused, and nothing will move until you resume it.
- [x] files are unable to sync — Dropbox could not sync those files and is telling you which. Click See issues beside it to get the list.
If you see files are unable to sync, go straight to that list. It names the files, which saves you guessing at the causes below.
Paused is worth a second look, because a paused Dropbox looks calm rather than broken. Dropbox is plain about what it costs you: changes you make won't update while it is paused.
Fixif it says paused, resume it from that same menu. If it says up to date but a file is missing, skip to the file section below.
A Mac on battery, or a hot one, syncs slowly on purpose
Sync crawls on a laptop away from a desk, then catches up once you plug it back in.
This one is documented and almost never mentioned. Dropbox says sync performance may slow to preserve battery life when your computer has low battery, is not plugged in, or is running hot.
So a slow sync on a warm laptop at 15% battery is Dropbox working as designed, not a fault. Nothing you change in the app will speed it up.
Fixplug the Mac in, give it a few minutes to cool, and look at the status again before you troubleshoot anything else.
One file can hold up the rest
Everything else syncs, but one file never does — or the same file name keeps appearing in the Dropbox window.
Two characters are refused outright. Dropbox's naming rules say the forward slash / and the backslash \ are always disallowed. Several more are allowed but not recommended, because they break on other systems:
<>:"|?*and the period.- A space at the end of a name. Dropbox says not to add one.
- A path of 260 characters or more. Dropbox's rule is that file paths must be fewer than 260 characters, counting the folders above the file.
Two more stop a single file while everything around it keeps working. A case conflict is when two names match except for capital letters. Dropbox can store both on the website but not in the folder on your Mac, so one gets (Case Conflict) added to its name. A Unicode encoding conflict is when two names look identical but are stored differently underneath; one gets (Unicode Encoding Conflict) added. Both are fixed by renaming one of them.
A file can also be held by the Mac rather than by Dropbox. Dropbox says that if your file is read-only, or is locked by a non-Dropbox application, it cannot sync. A document still open in Word or Preview is the usual culprit.
And a file can be set to be skipped deliberately. An ignored file stays on your Mac but is not kept on Dropbox's servers, so it will never reach your other devices. You can spot one by its icon, and which icon depends on which version you run. On recent Dropbox, built on File Provider, Dropbox describes it as a white cloud with a black outline and back slash. On the older engine it is a gray circle with a white minus sign.
Fixrename the file, close whatever has it open, or unlock it in the Finder's Get Info window. Dragging it to the Desktop and back in is a quick way to test whether that one file is the problem.
Check your Dropbox storage
Nothing uploads at all, not even a small text file.
When the account is full, Dropbox does not slow down. It stops. Their wording is that file syncing stops and you cannot upload new files, and you may see a notice saying your account is full and has stopped syncing.
This is storage on your Dropbox account, not space on the Mac. They run out separately, and the next section is the other one.
Fixsign in at dropbox.com and read the storage figure. Dropbox says syncing resumes once the account is no longer full, so freeing room or buying more is the whole fix.
Check the free space on the Mac
Uploads work but downloads never finish, and macOS has warned you the disk is nearly full.
A file set to online-only stays in the cloud until you open it. Dropbox says an online-only file still appears in your folder, but you can only open it when connected. Opening one downloads it, and that download needs room on the disk. This is why a Dropbox folder can look complete and still fail the moment you open something.
Fixcheck the free space in the Apple menu, under About This Mac, then Storage. If it is down to a couple of gigabytes, make room before anything else: a download that cannot be written will not complete, however healthy Dropbox is.
If the folder itself looks wrong
The Dropbox folder is not where you left it, or it is full of files that will not open offline.
Recent versions of Dropbox are built on File Provider, Apple's system for putting cloud storage into the Finder. Dropbox says this needs macOS 12.5 or later, and that on it your Dropbox folder will be moved to ~/Library/CloudStorage. Older installs keep it in your user folder instead.
That move surprises people, and a folder that looks empty in the old place is not a sync failure. Dropbox publishes a way to settle where yours actually is: a file named info.json at ~/.dropbox/info.json records the path.
One thing genuinely stopped working in this change. Dropbox says LAN sync is currently not supported, so two Macs on the same network no longer shortcut through it and both go via the internet.
Fixlook in ~/Library/CloudStorage first. In the Finder, press Shift-Command-G and paste that path.
Steps to leave for last
Dropbox's own first suggestions are to quit and relaunch the app, and to check what macOS lets it reach — its permissions. Both are reasonable and neither is free, so do them once the cheap checks above are done.
Quitting mid-upload is the risk worth naming. Let the status settle before you quit, or a file part-way up has to start again.
On permissions, Dropbox's instructions split by macOS version: on macOS 12 or earlier, grant it Full Disk Access and Accessibility; on macOS 13 and later, turn its permissions on in System Settings.
Fixquit Dropbox from its menu and open it again. If that changes nothing, check its entries under System Settings, then Privacy & Security.
Unlinking is milder than it sounds, with one sharp edge. Dropbox says the files already synced to that computer remain on that computer and can still be opened; what stops is syncing, until you sign back in. The edge is a checkbox in that same screen reading Delete files from [account name] Dropbox the next time this computer comes online. Of it Dropbox writes: “Once the deletion is initiated, it’s no longer connected to your account and can’t be undone.” That option is on paid plans only, so on a free account you will not see it at all.
Fixif you do unlink, read the checkbox before you confirm and leave it unticked. Anything set to online-only was never on the Mac to begin with, so expect to download those again afterwards. A reinstall on its own meets the same refused name, full account and full disk over again.
The short version
- Read the menu-bar status first. Files are unable to sync names the broken files outright, and paused looks calm rather than broken.
- A Mac on battery or running hot syncs slowly by design. Plug it in before troubleshooting.
- One file stops the rest: a slash in the name, a path of 260 characters or more, a case or Unicode conflict, a locked file, or one open in another app.
- A full Dropbox account stops syncing outright. A full disk stops downloads only.
- On recent macOS the folder lives in ~/Library/CloudStorage. A missing folder is often just a moved one.