docmirror/dev-sidecar · error

无效的代理端口号

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.

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 地址
• 未找到可用的 macOS 网络服务，无法设置系统代理
• ----- : , dns returned invalid ip
• 没有找到占用该端口的进程
• FreeEye runtime config is required.

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

Appendix: 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)