{"record":{"id":"5f0bc8979dd1a214","repo":"docmirror/dev-sidecar","slug":"unknown-os-type-os-platform-5f0bc8","errorCode":null,"errorMessage":"UNKNOWN OS TYPE '${os.platform()}'","messagePattern":"UNKNOWN OS TYPE '(.+?)'","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/shell/shell.js","lineNumber":164,"sourceCode":"    default:\n      throw new Error(`UNKNOWN OS TYPE ${os.platform()}`)\n  }\n}\n\nfunction getSystemPlatform (throwIfUnknown = false) {\n  switch (os.platform()) {\n    case 'darwin':\n      return 'mac'\n    case 'linux':\n      return 'linux'\n    case 'win32':\n      return 'windows'\n    case 'win64':\n      return 'windows'\n    default:\n      log.error(`UNKNOWN OS TYPE: ${os.platform()}`)\n      if (throwIfUnknown) {\n        throw new Error(`UNKNOWN OS TYPE '${os.platform()}'`)\n      } else {\n        return 'unknown-os'\n      }\n  }\n}\n\nasync function execute (executor, args) {\n  return executor[getSystemPlatform(true)](getSystemShell().exec, args)\n}\n\nasync function execFile (file, args, options) {\n  return new Promise((resolve, reject) => {\n    try {\n      childProcess.execFile(file, args, options, (err, stdout) => {\n        if (err) {\n          log.error('文件执行出错：', file, err)\n          reject(err)\n          return","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/docmirror/dev-sidecar/blob/7710cd56cce760c708f30b01d2d4056eb8c402d5/packages/core/src/shell/shell.js#L146-L182","documentation":"getSystemPlatform(throwIfUnknown) normalizes os.platform() to 'darwin'|'linux'|'windows'. Unknown platforms log an error and either return the sentinel 'unknown-os' or — when throwIfUnknown is true — throw this error. It is the platform-detection guard used by getSystemShell and execute before any shell command runs.","triggerScenarios":"Calling getSystemPlatform(true) (directly or via execute/getSystemShell) on a platform whose os.platform() string does not match the known cases: darwin/linux variants/win32/win64 — e.g. 'freebsd', 'sunos', 'android', 'openbsd'.","commonSituations":"FreeBSD/OpenBSD servers, Android via Termux, unusual embedded Node builds; running unit tests on an unsupported CI platform; executing CLI daemons on non-standard OS images.","solutions":["Run on a supported platform (macOS/Linux/Windows); `node -p process.platform` should print darwin/linux/win32","Use a supported container/VM image if the host OS is exotic","If you own the call, pass throwIfUnknown=false to get 'unknown-os' and degrade gracefully instead of throwing","Patch the switch in shell.js to map your platform if you maintain a fork"],"exampleFix":"// before\nconst platform = shell.getSystemPlatform(true) // throws 'UNKNOWN OS TYPE freebsd'\n// after\nlet platform\ntry {\n  platform = shell.getSystemPlatform(true)\n} catch (e) {\n  log.warn('Unsupported platform, disabling shell features', e)\n  platform = 'unknown-os'\n}","handlingStrategy":"fallback","validationCode":"const p = os.platform()\nif (!['darwin', 'linux', 'win32', 'win64'].includes(p)) {\n  log.warn(`Unknown platform ${p}; shell features disabled`)\n}","typeGuard":"function isKnownPlatform(p = os.platform()) { return ['darwin', 'linux', 'win32', 'win64'].includes(p) }","tryCatchPattern":"try {\n  const platform = shell.getSystemPlatform(true)\n} catch (e) {\n  if (String(e.message).startsWith('UNKNOWN OS TYPE')) {\n    return 'unknown-os' // degrade gracefully\n  }\n  throw e\n}","preventionTips":["Call getSystemPlatform(false) when you only need a best-effort result and can handle 'unknown-os'","Gate shell-dependent features behind a platform check at startup","Test on all target platforms in CI","Keep a fallback code path that skips shell operations on unsupported OSes"],"tags":["platform","operating-system","unsupported-platform"],"backgroundTag":"unsupported-os-platform","analyzedSha":"7710cd56cce760c708f30b01d2d4056eb8c402d5","analyzedAt":"2026-08-31T22:07:07.234Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}