What causes "Unknown single instance type ${mutexType}" in yarnpkg/yarn?

Use `--mutex file: ` for a filesystem-based lock, e.g. `--mutex file:/tmp/.yarn-mutex`.

yarnpkg/yarn · error · MessageError

Unknown single instance type ${mutexType}

Error message

Unknown single instance type ${mutexType}

What it means

Thrown when the `--mutex` CLI flag is parsed and its type prefix (before the first `:`) is neither `'file'` nor `'network'`. Yarn uses the mutex to guarantee single-instance execution, and only two transport types are implemented.

Source

Thrown at src/cli/index.js:592

      const mutex: mixed = commander.mutex;
      if (mutex && typeof mutex === 'string') {
        const separatorLoc = mutex.indexOf(':');
        let mutexType;
        let mutexSpecifier;
        if (separatorLoc === -1) {
          mutexType = mutex;
          mutexSpecifier = undefined;
        } else {
          mutexType = mutex.substring(0, separatorLoc);
          mutexSpecifier = mutex.substring(separatorLoc + 1);
        }

        if (mutexType === 'file') {
          return runEventuallyWithFile(mutexSpecifier, true).then(exit);
        } else if (mutexType === 'network') {
          return runEventuallyWithNetwork(mutexSpecifier).then(exit);
        } else {
          throw new MessageError(`Unknown single instance type ${mutexType}`);
        }
      } else {
        return run().then(exit);
      }
    })
    .catch((err: Error) => {
      reporter.verbose(err.stack);

      if (err instanceof ProcessTermError && reporter.isSilent) {
        return exit(err.EXIT_CODE || 1);
      }

      if (err instanceof MessageError) {
        reporter.error(err.message);
      } else {
        onUnexpectedError(err);
      }

View on GitHub (pinned to c2dda503f3)

Solutions

Use `--mutex file:<path>` for a filesystem-based lock, e.g. `--mutex file:/tmp/.yarn-mutex`.
Use `--mutex network:<port>` for a network-based lock, e.g. `--mutex network:31997`.
Remove the `--mutex` flag entirely if single-instance enforcement is not needed.
Check for typos in the type token before the first colon.

Example fix

# before
yarn install --mutex fiel:/tmp/.yarn-mutex
# after
yarn install --mutex file:/tmp/.yarn-mutex

Defensive patterns

Strategy: validation

Validate before calling

const VALID_MUTEX_TYPES = new Set(['file', 'network']);
function validateMutex(mutex) {
  if (!mutex || typeof mutex !== 'string') return null;
  const type = mutex.split(':')[0];
  if (!VALID_MUTEX_TYPES.has(type)) {
    throw new Error(`Invalid --mutex type '${type}'. Use 'file:<path>' or 'network:<port>'.`);
  }
  return {type, specifier: mutex.substring(type.length + 1)};
}

Type guard

function isValidMutex(mutex) {
  if (typeof mutex !== 'string') return false;
  const type = mutex.split(':')[0];
  return type === 'file' || type === 'network';
}

Try / catch

try {
  await runWithMutex(mutex);
} catch (err) {
  if (err instanceof MessageError && err.message.startsWith('Unknown single instance type')) {
    reporter.error('Use --mutex file:<path> or --mutex network:<port>.');
    process.exit(1);
  }
  throw err;
}

Prevention

Validate the --mutex value in your wrapper script before invoking Yarn.
Document the two supported mutex types for your team to prevent typos.
Prefer omitting --mutex unless concurrent Yarn runs are a real concern.

When it happens

Trigger: Passing `--mutex <type>:<specifier>` where `<type>` is anything other than `file` or `network` (e.g. `--mutex semaphore:foo`, `--mutex redis:localhost`). Also a bare typo like `--mutex fiel:/tmp/yarn.lock`.

Common situations: Misreading the docs and guessing a mutex type. Copy-pasting a mutex string from an incompatible tool. Typo in CI environment variable that feeds `--mutex`.

Related errors

AI-assisted analysis of yarnpkg/yarn@c2dda503f3 (2026-08-13). Data as JSON: /api/errors/b74c96b516be753f. Report an issue: GitHub.