docmirror/dev-sidecar · error

未找到处于 LISTENING 状态的进程

Error message

未找到处于 LISTENING 状态的进程

What it means

On Windows, kill-by-port first tries PowerShell (Get-NetTCPConnection) and falls back to parsing `netstat -aon` output for a line containing LISTENING on the target port. This error is thrown from the CMD fallback when netstat returned output but no line with the port was in LISTENING state (or no numeric PID could be extracted), so no taskkill was issued. It signals the port is not actually held by a LISTENING TCP socket.

Source

Thrown at packages/core/src/shell/scripts/kill-by-port.js:47

          throw new Error('没有找到占用该端口的进程')
        }

        // 解析 netstat 输出，提取处于 LISTENING 状态的 PID
        const lines = output.split(/\r?\n/)
        let killed = false
        for (const line of lines) {
          if (!line.includes('LISTENING')) {
            continue
          }
          const parts = line.trim().split(/\s+/)
          const pid = parts[parts.length - 1]
          if (pid && /^\d+$/.test(pid)) {
            await exec([`taskkill /f /pid ${pid} /t`], { type: 'cmd', printErrorLog: false })
            killed = true
          }
        }
        if (!killed) {
          throw new Error('未找到处于 LISTENING 状态的进程')
        }
        return true
      } catch (cmdError) {
        // 两种方案都失败，抛出包含原始错误信息的异常
        throw new Error(
          `终止占用端口 ${port} 的进程失败。\n`
          + `PowerShell 方案: ${psError.message}\n`
          + `CMD 方案: ${cmdError.message}`,
        )
      }
    }
  },

  async linux (exec, { port }) {
    // 主方案：lsof
    try {
      await exec(`kill $(lsof -i:${port} -t 2>/dev/null) 2>/dev/null || true`)
      return true

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Verify a process actually LISTENs on the port: run `netstat -aon | findstr LISTENING | findstr :<port>` and check the PID exists.
2. If PowerShell is available, retry so the primary Get-NetTCPConnection path is used instead of the netstat fallback.
3. If only a TIME_WAIT socket remains, no action is needed — wait for it to expire or use a different port.
4. If the listener is UDP, find it with `netstat -aon -p UDP` and kill the PID manually with `taskkill /f /pid <pid> /t`.

Example fix

// before: assuming any output means a killable listener
const output = await exec([`netstat -aon | find ":${port}"`], { type: 'cmd', printErrorLog: false })
// after: filter for LISTENING lines up-front and fail fast with a clearer message
const listening = output.split(/\r?\n/).filter(l => l.includes('LISTENING'))
if (listening.length === 0) {
  throw new Error(`端口 ${port} 上没有处于 LISTENING 状态的进程（可能仅有 TIME_WAIT 或 UDP 占用）`)
}

const { execSync } = require('child_process')
const out = execSync('netstat -aon', { encoding: 'utf8' })
const listening = out.split(/\r?\n/).some(l => l.includes(`:${port}`) && l.includes('LISTENING'))
if (!listening) console.warn(`no LISTENING process on port ${port}; skip kill`)

function hasListeningPid(netstatLine) {
  const parts = netstatLine.trim().split(/\s+/)
  return netstatLine.includes('LISTENING') && /^\d+$/.test(parts[parts.length - 1])
}

try {
  await killByPort({ port })
} catch (e) {
  if (e.message.includes('未找到处于 LISTENING 状态的进程')) {
    // port not held by a listener — safe to proceed / start your own server
  } else {
    throw e
  }
}

When it happens

Trigger: Calling DevSidecar's kill-by-port shell script (executor.windows) on Windows where: (1) the port is used only by a UDP binding or an outbound (non-LISTEN) TCP connection, (2) the netstat line for the port has a non-numeric last column (e.g. some localized Windows outputs or TIME_WAIT entries matched by `find ":port"`), or (3) the PowerShell attempt failed first (no Get-NetTCPConnection) and netstat shows the port but not in LISTENING state.

Common situations: Killing a leftover proxy port (31180/31181) after an app crashed; the owning process already exited and only a TIME_WAIT socket remains; a UDP-only listener (e.g. DNS on port 53) matched by the find filter; non-English Windows where netstat state strings differ.

Related errors

• 终止占用端口 ${port} 的进程失败。 PowerShell 方案: ${psError.message} CMD
• 没有找到占用该端口的进程
• 终止占用端口 ${port} 的进程失败。 lsof 方案失败 fuser 方案: ${fuserError.messa
• 无效的代理端口号: ${port}
• 证书路径为空，无法安装根证书。请确认证书文件已生成。

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