docmirror/dev-sidecar · error

证书路径为空，无法安装根证书。请确认证书文件已生成。

Error message

证书路径为空，无法安装根证书。请确认证书文件已生成。

What it means

During Windows root-CA installation, the setup-ca executor expects the path of the generated dev-sidecar CA certificate. When setupCa() is invoked with certPath undefined/empty, it throws this error instead of running `start <certPath>`. It signals that the CA certificate generation step never produced a path, so installation cannot proceed.

Source

Thrown at packages/core/src/shell/scripts/setup-ca.js:9

const fs = require('node:fs')
const Shell = require('../shell')

const execute = Shell.execute

const executor = {
  async windows (exec, { certPath }) {
    if (!certPath) {
      throw new Error('证书路径为空，无法安装根证书。请确认证书文件已生成。')
    }
    if (!fs.existsSync(certPath)) {
      throw new Error(`证书文件不存在: ${certPath}`)
    }
    const cmds = [`start "" "${certPath}"`]
    await exec(cmds, { type: 'cmd' })
    return true
  },
  async linux (exec, { certPath }) {
    if (!certPath) {
      throw new Error('证书路径为空，无法安装根证书。请确认证书文件已生成。')
    }
    if (!fs.existsSync(certPath)) {
      throw new Error(`证书文件不存在: ${certPath}`)
    }
    const cmds = [`sudo cp ${certPath} /usr/local/share/ca-certificates`, 'sudo update-ca-certificates ']
    await exec(cmds)
    return true

View on GitHub (pinned to 7710cd56cc)

Solutions

1. Ensure the CA certificate is generated first (restart the app so the core cert module regenerates ~/.dev-sidecar/dev-sidecar.ca.crt)
2. Check user config (~/.dev-sidecar/config.json) for an empty/overridden cert path and remove it so the default path is used
3. Verify ~/.dev-sidecar is writable by the current user
4. If calling the API directly, pass a valid certPath: setupCa(exec, { certPath: '~/.dev-sidecar/dev-sidecar.ca.crt' })

Example fix

// before
await shell.setupCa(exec, { certPath: config.cert && config.cert.path }) // undefined when cert config missing
// after
const certPath = (config.cert && config.cert.path) || getDefaultCaCertPath()
if (!fs.existsSync(certPath)) await certApi.generateRootCert()
await shell.setupCa(exec, { certPath })

const fs = require('fs')
const path = require('path')
const certPath = path.join(os.homedir(), '.dev-sidecar', 'dev-sidecar.ca.crt')
if (!certPath) throw new Error('certPath must be resolved before setupCa')

function hasCertPath(opts) { return opts != null && typeof opts.certPath === 'string' && opts.certPath.trim() !== '' }

try {
  await shell.setupCa(exec, { certPath })
} catch (e) {
  if (String(e.message).includes('证书路径为空')) {
    log.error('CA cert not generated yet; regenerate before install')
    await certApi.generateRootCert()
    await shell.setupCa(exec, { certPath })
  } else { throw e }
}

When it happens

Trigger: Calling setupCa(exec, { certPath: undefined }) / ({ certPath: '' }) on Windows; the caller (typically the core cert module) failed to resolve the CA path (e.g. cert generation was skipped, or the cert config was overridden to empty) before invoking the executor.

Common situations: First-run CA generation failed or was interrupted so no cert file was created; user config pointed `cert.certPath` to an empty value; calling the shell setup script directly without passing certPath; ~/.dev-sidecar directory not writable so cert generation silently failed.

Related errors

• 证书文件不存在: ${certPath}
• FreeEye runtime config is required.
• 没有找到占用该端口的进程
• 未找到处于 LISTENING 状态的进程
• 终止占用端口 ${port} 的进程失败。 PowerShell 方案: ${psError.message} CMD

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