docmirror/dev-sidecar · error

UNKNOWN OS TYPE ${os.platform()}

Error message

UNKNOWN OS TYPE ${os.platform()}

What it means

getSystemShell() maps os.platform() to a system-shell implementation (Darwin/Linux/Windows). If os.platform() returns anything other than darwin/linux/win32 (e.g. 'freebsd', 'openbsd', 'android', 'aix'), no shell implementation exists and this error is thrown immediately, so Shell.execute() cannot run any command.

Source

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

        // log.info('cmd 命令完成：', stdout)
        resolve(stdout.replace('Active code page: 65001\r\n', ''))
      }
      // log.info('关闭 cmd')
      // ps.kill('SIGINT')
    })
  })
}

function getSystemShell () {
  switch (getSystemPlatform(true)) {
    case 'mac':
      return DarwinSystemShell
    case 'linux':
      return LinuxSystemShell
    case 'windows':
      return WindowsSystemShell
    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 {

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Run dev-sidecar on a supported platform: macOS (darwin), Linux, or Windows (win32)
2. If on FreeBSD/OpenBSD, use a Linux VM/container or jail Linux emulation instead
3. Check `node -e "console.log(process.platform)"` to confirm the platform Node reports
4. Add/patch a shell implementation for the platform if you must support it (fork and extend shell.js switch)

Example fix

// before
await Shell.execute('ls', {}) // throws on freebsd
// after
const p = os.platform()
if (!['darwin', 'linux', 'win32'].includes(p)) {
  throw new Error(`Unsupported platform ${p}; use macOS/Linux/Windows`)
}
await Shell.execute('ls', {})

const SUPPORTED = ['darwin', 'linux', 'win32']
if (!SUPPORTED.includes(os.platform())) {
  throw new Error(`Unsupported platform: ${os.platform()}. Use macOS/Linux/Windows.`)
}

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

try {
  await Shell.execute(cmd, opts)
} catch (e) {
  if (String(e.message).startsWith('UNKNOWN OS TYPE')) {
    log.error('Shell commands unavailable on this platform')
    return null
  }
  throw e
}

When it happens

Trigger: Running dev-sidecar (or calling Shell.execute/getSystemShell directly) on an OS whose os.platform() is not one of darwin|linux|win32; notably 'freebsd', 'openbsd', 'android' (Termux), or exotic platforms.

Common situations: Deploying the CLI to a FreeBSD server or Android/Termux environment; running in an unusual Node build (e.g. cygwin/msys reporting a non-win32 platform in some setups); CI images on unsupported platforms.

Related errors

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

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