What causes "UNKNOWN OS TYPE '${os.platform()}'" in docmirror/dev-sidecar?

Run on a supported platform (macOS/Linux/Windows); `node -p process.platform` should print darwin/linux/win32

UNKNOWN OS TYPE '${os.platform()}'

Error message

UNKNOWN OS TYPE '${os.platform()}'

What it means

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.

Source

Thrown at packages/core/src/shell/shell.js:164

    default:
      throw new Error(`UNKNOWN OS TYPE ${os.platform()}`)
  }
}

function getSystemPlatform (throwIfUnknown = false) {
  switch (os.platform()) {
    case 'darwin':
      return 'mac'
    case 'linux':
      return 'linux'
    case 'win32':
      return 'windows'
    case 'win64':
      return 'windows'
    default:
      log.error(`UNKNOWN OS TYPE: ${os.platform()}`)
      if (throwIfUnknown) {
        throw new Error(`UNKNOWN OS TYPE '${os.platform()}'`)
      } else {
        return 'unknown-os'
      }
  }
}

async function execute (executor, args) {
  return executor[getSystemPlatform(true)](getSystemShell().exec, args)
}

async function execFile (file, args, options) {
  return new Promise((resolve, reject) => {
    try {
      childProcess.execFile(file, args, options, (err, stdout) => {
        if (err) {
          log.error('文件执行出错：', file, err)
          reject(err)
          return

View on GitHub (pinned to 7710cd56cc)

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

Example fix

// before
const platform = shell.getSystemPlatform(true) // throws 'UNKNOWN OS TYPE freebsd'
// after
let platform
try {
  platform = shell.getSystemPlatform(true)
} catch (e) {
  log.warn('Unsupported platform, disabling shell features', e)
  platform = 'unknown-os'
}

Defensive patterns

Strategy: fallback

Validate before calling

const p = os.platform()
if (!['darwin', 'linux', 'win32', 'win64'].includes(p)) {
  log.warn(`Unknown platform ${p}; shell features disabled`)
}

Type guard

function isKnownPlatform(p = os.platform()) { return ['darwin', 'linux', 'win32', 'win64'].includes(p) }

Try / catch

try {
  const platform = shell.getSystemPlatform(true)
} catch (e) {
  if (String(e.message).startsWith('UNKNOWN OS TYPE')) {
    return 'unknown-os' // degrade gracefully
  }
  throw e
}

Prevention

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

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

UNKNOWN OS TYPE ${os.platform()}

AI-assisted analysis of docmirror/dev-sidecar@7710cd56cc (2026-08-31). Data as JSON: /api/errors/5f0bc8979dd1a214. Report an issue: GitHub.