{"record":{"id":"b74c96b516be753f","repo":"yarnpkg/yarn","slug":"unknown-single-instance-type-mutextype","errorCode":null,"errorMessage":"Unknown single instance type ${mutexType}","messagePattern":"Unknown single instance type (.+?)","errorType":"exception","errorClass":"MessageError","httpStatus":null,"severity":"error","filePath":"src/cli/index.js","lineNumber":592,"sourceCode":"      const mutex: mixed = commander.mutex;\n      if (mutex && typeof mutex === 'string') {\n        const separatorLoc = mutex.indexOf(':');\n        let mutexType;\n        let mutexSpecifier;\n        if (separatorLoc === -1) {\n          mutexType = mutex;\n          mutexSpecifier = undefined;\n        } else {\n          mutexType = mutex.substring(0, separatorLoc);\n          mutexSpecifier = mutex.substring(separatorLoc + 1);\n        }\n\n        if (mutexType === 'file') {\n          return runEventuallyWithFile(mutexSpecifier, true).then(exit);\n        } else if (mutexType === 'network') {\n          return runEventuallyWithNetwork(mutexSpecifier).then(exit);\n        } else {\n          throw new MessageError(`Unknown single instance type ${mutexType}`);\n        }\n      } else {\n        return run().then(exit);\n      }\n    })\n    .catch((err: Error) => {\n      reporter.verbose(err.stack);\n\n      if (err instanceof ProcessTermError && reporter.isSilent) {\n        return exit(err.EXIT_CODE || 1);\n      }\n\n      if (err instanceof MessageError) {\n        reporter.error(err.message);\n      } else {\n        onUnexpectedError(err);\n      }\n","sourceCodeStart":574,"sourceCodeEnd":610,"githubUrl":"https://github.com/yarnpkg/yarn/blob/c2dda503f3759b5be5f0e24ecd9cf5c97a540147/src/cli/index.js#L574-L610","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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`.","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."],"exampleFix":"# before\nyarn install --mutex fiel:/tmp/.yarn-mutex\n# after\nyarn install --mutex file:/tmp/.yarn-mutex","handlingStrategy":"validation","validationCode":"const VALID_MUTEX_TYPES = new Set(['file', 'network']);\nfunction validateMutex(mutex) {\n  if (!mutex || typeof mutex !== 'string') return null;\n  const type = mutex.split(':')[0];\n  if (!VALID_MUTEX_TYPES.has(type)) {\n    throw new Error(`Invalid --mutex type '${type}'. Use 'file:<path>' or 'network:<port>'.`);\n  }\n  return {type, specifier: mutex.substring(type.length + 1)};\n}","typeGuard":"function isValidMutex(mutex) {\n  if (typeof mutex !== 'string') return false;\n  const type = mutex.split(':')[0];\n  return type === 'file' || type === 'network';\n}","tryCatchPattern":"try {\n  await runWithMutex(mutex);\n} catch (err) {\n  if (err instanceof MessageError && err.message.startsWith('Unknown single instance type')) {\n    reporter.error('Use --mutex file:<path> or --mutex network:<port>.');\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["cli","mutex","config"],"backgroundTag":null,"analyzedSha":"c2dda503f3759b5be5f0e24ecd9cf5c97a540147","analyzedAt":"2026-08-13T04:17:06.305Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}