docmirror/dev-sidecar · warning

加载 free-eye 插件失败，该插件不可用:

Error message

加载 free-eye 插件失败，该插件不可用:

What it means

Warning logged by the free_eye getter in modules/plugin/index.js when require('./free-eye') throws. free-eye is an ESM module consumed via CJS require() (unwrapping .default); in Node SEA single-executable builds the module cannot be packaged/required, so the getter degrades gracefully: it logs this warning and returns null, which causes expose.js to register the plugin as disabled instead of crashing startup.

Source

Thrown at packages/core/src/modules/plugin/index.js:13

module.exports = {
  node: require('./node'),
  git: require('./git'),
  pip: require('./pip'),
  overwall: require('./overwall'),
  // free-eye 为 ESM 模块，CJS require() 得到 { default: ... }，需解包
  // 独立可执行文件（SEA）中无法打包/携带 free-eye，加载失败时降级为不可用，而不是崩溃
  get free_eye () {
    try {
      return require('./free-eye').default
    } catch (e) {
      const log = require('@docmirror/dev-sidecar/src/utils/util.log-or-console')
      log.warn('加载 free-eye 插件失败，该插件不可用:', e.message)
      return null
    }
  },
}

View on GitHub (pinned to 7710cd56cc)

Solutions

1. If running the SEA build, this is expected degradation — ignore the warning or don't rely on free-eye in standalone builds.
2. Reinstall dependencies (pnpm install from repo root) to restore the free-eye module and its dependencies.
3. Verify packages/core/src/modules/plugin/free-eye exists and loads under your Node version (Node 22.x recommended); fix version or module resolution if not.
4. Read the logged e.message for the root require() failure and address it (missing file, syntax error, or missing dependency).

let freeEye = null
try { freeEye = require('@docmirror/dev-sidecar/src/modules/plugin/free-eye').default } catch (e) { /* unavailable */ }
if (freeEye == null) console.warn('free-eye not available in this environment')

function isFreeEyeAvailable(mods) {
  try { return mods?.plugin?.free_eye != null } catch { return false }
}

try {
  const freeEye = modules.plugin.free_eye
  if (freeEye) await startFreeEye(freeEye)
} catch (e) {
  console.warn('free-eye unavailable, continuing without it:', e.message)
}

When it happens

Trigger: Any access to modules.plugin.free_eye (during expose.js startup or direct module access) where require('./free-eye') fails — SEA builds without the ESM asset, missing free-eye directory after an incomplete install, or an error thrown while evaluating the free-eye module (its dependencies absent or incompatible).

Common situations: Running the packaged SEA standalone executable where free-eye was never bundled; a corrupted or partial pnpm install that omitted the free-eye subfolder/dependencies; a Node version mismatch breaking the ESM/CJS interop for that module.

Related errors

• 插件【${key}】不可用，已注册为禁用状态
• 插件【${key}】不可用，无法启动
• 插件【${key}】不可用
• Tests directory not found: ${resolvedDir}
• FreeEye runtime config is required.

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