parcel-bundler/parcel · error · Error

A Parcel link already exists! Try `parcel-link unlink` to re

Error message

A Parcel link already exists! Try `parcel-link unlink` to re-link.

What it means

Thrown by parcel-link's link command when an existing ParcelLinkConfig is already loaded for the current app root (appRoot = process.cwd()). The command intentionally prevents stacking two links; it tells you to unlink first. Note the loader's own error is swallowed ('// boop!'), so only a successfully loaded prior config triggers this.

Source

Thrown at packages/dev/parcel-link/src/link.js:178

      '-g, --node-modules-glob <glob>',
      'Location where node_modules should be linked in the app.\nCan be repeated with multiple globs.',
      (glob, globs) => globs.concat([glob.replace(/["']/g, '')]),
      ['node_modules'],
    )
    .action(async (packageRoot, options) => {
      if (options.dryRun) log('Dry run...');
      let appRoot = process.cwd();

      let parcelLinkConfig;

      try {
        parcelLinkConfig = await ParcelLinkConfig.load(appRoot, {fs});
      } catch (e) {
        // boop!
      }

      if (parcelLinkConfig) {
        throw new Error(
          'A Parcel link already exists! Try `parcel-link unlink` to re-link.',
        );
      }

      parcelLinkConfig = new ParcelLinkConfig({
        fs,
        appRoot,
        packageRoot: packageRoot ?? path.join(__dirname, '../../../'),
        namespace: options.namespace,
        nodeModulesGlobs: options.nodeModulesGlob,
      });

      await action(parcelLinkConfig, {dryRun: options.dryRun, log});

      if (!options.dryRun) await parcelLinkConfig.save();

      log('🎉 Linking successful');
    });

View on GitHub (pinned to 59484858a1)

Solutions

1. Run `parcel-link unlink` first to remove the existing link, then re-link.
2. Manually remove the ParcelLinkConfig file in appRoot if unlink fails, then retry.
3. Confirm you are in the intended appRoot (`pwd`) — a wrong cwd can see a different app's link config.
4. If the prior link is stale, inspect the config and clean up node_modules symlinks before re-linking.

Example fix

# before
$ parcel-link link
# Error: A Parcel link already exists!

# after
$ parcel-link unlink
$ parcel-link link

let existing;
try { existing = await ParcelLinkConfig.load(appRoot, { fs }); } catch { /* none */ }
if (existing) {
  console.error('A link already exists; run `parcel-link unlink` first.');
  process.exit(1);
}

try { await linkCommand(appRoot); }
catch (e) {
  if (/A Parcel link already exists/.test(e.message)) {
    await unlinkCommand(appRoot);
    await linkCommand(appRoot);
  } else throw e;
}

When it happens

Trigger: Running `parcel-link link` (or the action) in a directory where a previous `parcel-link` succeeded and wrote its config (typically a .parcel-link marker/config file that ParcelLinkConfig.load can read).

Common situations: Re-running parcel-link after a prior link without unlinking; switching branches where a prior link config was committed; partial cleanup that left the link config behind.

Related errors

• `origin` must be an absolute path
• A Parcel link could not be found!

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/e37705f9c1588058. Report an issue: GitHub.