docmirror/dev-sidecar · error

无效的代理端口号: ${port}

Error message

无效的代理端口号: ${port}

What it means

validateProxyPort strict-checks the TCP port used in macOS networksetup/sudo commands: Number(port) must be an integer in 1–65535. Otherwise this error is thrown before any privileged command runs, guarding the sudo path from malformed or injected port values.

Source

Thrown at packages/core/src/shell/scripts/set-system-proxy/index.js:311

/**
 * Strict-validate a proxy host (IPv4 / IPv6 / hostname) and throw if the
 * value looks suspicious.  This is a defence-in-depth guard for the sudo
 * execution path; the primary protection is `shellEscapeArg`.
 */
function validateProxyIp (ip) {
  if (typeof ip !== 'string' || !/^[\w.\-:[\]]+$/.test(ip)) {
    throw new Error(`无效的代理 IP 地址: ${ip}`)
  }
}

/**
 * Strict-validate a TCP port number.
 */
function validateProxyPort (port) {
  const n = Number(port)
  if (!Number.isInteger(n) || n < 1 || n > 65535) {
    throw new Error(`无效的代理端口号: ${port}`)
  }
}

function sudoExecMac (cmd) {
  return new Promise((resolve, reject) => {
    log.info('以管理员权限执行命令:', cmd)
    sudoPrompt.exec(cmd, { name: 'dev-sidecar' }, (error, stdout, stderr) => {
      if (stderr) {
        log.warn('以管理员权限执行命令，stderr:', stderr)
      }
      if (error) {
        log.error('以管理员权限执行命令失败:', error)
        reject(error)
      } else {
        resolve(stdout)
      }
    })
  })

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Pass an integer between 1 and 65535 (dev-sidecar's default HTTPS port is 31181).
2. Inspect ~/.dev-sidecar/config.json and running.json for the port value; fix or delete the bad entry to fall back to defaults.
3. Coerce and check before calling: `const p = Number(port); if (!Number.isInteger(p) || p < 1 || p > 65535) throw ...`.
4. Ensure the config merge layer (remote shared/personal) is not overriding the port with an invalid value.

Example fix

// before
await api.shell.setSystemProxy({ ip: '127.0.0.1', port: config.proxyPort }) // config.proxyPort may be '' / undefined
// after
const port = Number(config.proxyPort) || 31181
if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('bad proxy port')
await api.shell.setSystemProxy({ ip: '127.0.0.1', port })

function isValidProxyPort(port) {
  const n = Number(port)
  return Number.isInteger(n) && n >= 1 && n <= 65535
}
if (!isValidProxyPort(port)) throw new Error(`fix config: bad proxy port ${JSON.stringify(port)}`)

function isProxyPort(v) {
  const n = Number(v)
  return Number.isInteger(n) && n >= 1 && n <= 65535
}

try {
  await setSystemProxy({ ip, port })
} catch (e) {
  if (e.message.includes('无效的代理端口号')) {
    const fallbackPort = 31181 // dev-sidecar default HTTPS port
    if (isProxyPort(fallbackPort)) return setSystemProxy({ ip, port: fallbackPort })
  }
  throw e
}

When it happens

Trigger: Calling the macOS set-system-proxy script with a port that is: undefined/null, 0, negative, > 65535, a non-numeric string ('abc', '31,181'), or a non-integer number (31181.5) — including NaN from failed config parsing.

Common situations: Corrupted ~/.dev-sidecar/config.json where the proxy port field is empty or textual; remote/personal config layers supplying a bad port; the mitmproxy HTTPS port variable not initialized before the shell script runs.

Related errors

• 无效的代理 IP 地址: ${ip}
• 未找到可用的 macOS 网络服务，无法设置系统代理
• FreeEye runtime config is required.
• 没有找到占用该端口的进程
• 未找到处于 LISTENING 状态的进程

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