synced-folder-guard

Stop wasting an hour on EPERM / EBADF / TAR_BAD_ARCHIVE errors. This tool warns you before you install packages inside a cloud-synced folder.

Running npm install (or pip, cargo, yarn, pnpm) inside Google Drive, OneDrive, Dropbox, or iCloud Drive is one of the most confusing failures in dev tooling. The sync client fights the package manager for the same files mid-write, and you get a wall of errors like:

npm warn tar TAR_BAD_ARCHIVE: Unrecognized archive format
npm warn tar TAR_ENTRY_ERROR EBADF: bad file descriptor, write
npm warn tar TAR_ENTRY_ERROR EPERM: operation not permitted, write
Error: Cannot find module 'ajv'

Every guide tells you the same thing — after you've already lost the time: "clear your cache, delete node_modules, move the project." synced-folder-guard flips that: it tells you before the install, in one second.

Install

npm install -g synced-folder-guard

Or run it once with no install:

npx synced-folder-guard

Usage

Check the current folder:

synced-folder-guard          # or the short alias: sfg

If you're safe:

OK  not in a cloud-synced folder: C:\Users\you\repos\my-app

If you're not:

WARNING  this folder is inside a cloud-synced location.

  Path:     G:\My Drive\repos\my-app
  Provider: Google Drive
    - Google Drive (folder name "My Drive")

  Installing packages here often fails or silently corrupts, with errors like:
    EPERM, EBADF, ENOENT, TAR_BAD_ARCHIVE, "Unrecognized archive format"

  Fix: move this project to a non-synced folder (e.g. a local repos dir),
       or pause syncing for the duration of the install.

Check a specific path:

synced-folder-guard "G:\My Drive\repos\my-app"

Guard your installs automatically

Add it as a preinstall script so a bad location can never bite you again:

{
  "scripts": {
    "preinstall": "synced-folder-guard --fail"
  }
}

With --fail, the install aborts (exit code 1) when the project lives in a synced folder.

Options

| Flag | Description | |------|-------------| | -f, --fail | Exit with code 1 if the folder is synced (use in preinstall) | | --json | Machine-readable JSON output | | -q, --quiet | Print nothing when the folder is safe | | --no-color | Disable colored output | | -h, --help | Show help | | -v, --version | Show version |

Use as a library

const { detect } = require('synced-folder-guard');

const result = detect(process.cwd());
// {
//   path: 'G:\\My Drive\\repos\\my-app',
//   synced: true,
//   matches: [{ provider: 'Google Drive', via: 'folder name "My Drive"' }]
// }

if (result.synced) {
  console.warn(`Heads up: ${result.matches[0].provider} folder detected.`);
}

What it detects

| Provider | How | |----------|-----| | Google Drive | My Drive, Shared drives, Google Drive, GoogleDrive-* (macOS CloudStorage) folder names | | OneDrive | $OneDrive / $OneDriveCommercial / $OneDriveConsumer env vars, and OneDrive / OneDrive - Company folder names | | Dropbox | Real folder location read from Dropbox's own info.json, plus the Dropbox folder name | | iCloud Drive | Mobile Documents / com~apple~CloudDocs folder names |

Detection is segment-boundary aware, so a folder like MyDropboxNotes is not a false positive.

Why this happens

Cloud sync clients use placeholder/virtual files and aggressively lock files to upload them. Package managers extract thousands of small files and rename them rapidly. When both touch the same file at the same moment, the write fails — sometimes loudly (EPERM), sometimes silently (a half-extracted tarball that breaks require later). The only reliable fix is to keep node_modules out of the synced folder entirely.

Zero dependencies

Pure Node, no runtime dependencies. Works on Windows, macOS, and Linux. Node >=16.

License

MIT