{"record":{"id":"9e144523188b8152","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"unable-to-resolve-openclaw-root-set-openclaw-root","errorCode":null,"errorMessage":"Unable to resolve OpenClaw root. Set OPENCLAW_ROOT or run `pnpm build`.","messagePattern":"Unable to resolve OpenClaw root\\. Set OPENCLAW_ROOT or run `pnpm build`\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"MemoryCore/src/utils/clean-context-runner.ts","lineNumber":130,"sourceCode":"    dir = parent;\n  }\n}\n\nfunction resolveOpenClawRoot(): string {\n  if (_rootCache) return _rootCache;\n  const override = getEnv(\"OPENCLAW_ROOT\")?.trim();\n  if (override) { _rootCache = override; return override; }\n\n  const candidates = new Set<string>();\n  if (process.argv[1]) candidates.add(path.dirname(process.argv[1]));\n  candidates.add(process.cwd());\n  try { candidates.add(path.dirname(fileURLToPath(import.meta.url))); } catch { /* ignore */ }\n\n  for (const start of candidates) {\n    const found = findPackageRoot(start, \"openclaw\");\n    if (found) { _rootCache = found; return found; }\n  }\n  throw new Error(\"Unable to resolve OpenClaw root. Set OPENCLAW_ROOT or run `pnpm build`.\");\n}\n\nlet _loadPromise: Promise<RunEmbeddedPiAgentFn> | null = null;\n\nfunction loadRunEmbeddedPiAgent(logger?: RunnerLogger): Promise<RunEmbeddedPiAgentFn> {\n  if (_loadPromise) return _loadPromise;\n\n  _loadPromise = (async () => {\n    const t0 = Date.now();\n    const distPath = path.join(resolveOpenClawRoot(), \"dist\", \"extensionAPI.js\");\n    if (!fsSync.existsSync(distPath)) {\n      throw new Error(`Missing core module at ${distPath}. Run \\`pnpm build\\` or install the official package.`);\n    }\n    const mod = await import(pathToFileURL(distPath).href);\n    if (typeof mod.runEmbeddedPiAgent !== \"function\") {\n      throw new Error(\"runEmbeddedPiAgent not exported from dist/extensionAPI.js\");\n    }\n    logger?.info(`${TAG} loadRunEmbeddedPiAgent: dist/ import OK (${Date.now() - t0}ms)`);","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/MemoryCore/src/utils/clean-context-runner.ts#L112-L148","documentation":"resolveOpenClawRoot locates the openclaw package root by walking up from well-known starting points (and OPENCLAW_ROOT). If no candidate directory contains the openclaw package, the runner cannot locate dist/extensionAPI.js and throws, telling you to set OPENCLAW_ROOT explicitly or build the package with `pnpm build`.","triggerScenarios":"Calling the clean-context runner (directly or via loadRunEmbeddedPiAgent/distPath) when the openclaw package is not installed, is installed but unbuilt, or OPENCLAW_ROOT points to the wrong directory.","commonSituations":"Fresh checkout without running `pnpm build`; running from a bundled/standalone context where import.meta.url candidates don't resolve into the package; monorepo layout changes moving the package root; OPENCLAW_ROOT set to src instead of the package dir.","solutions":["Run `pnpm build` in the openclaw package so the package root with dist/ exists","Set OPENCLAW_ROOT to the absolute path of the openclaw package root","Install the official openclaw package if it is missing from node_modules","Verify findPackageRoot's candidate start dirs include your runtime location (e.g. when bundled)"],"exampleFix":"// before\nOPENCLAW_ROOT=./openclaw/src\n// after\nOPENCLAW_ROOT=/abs/path/to/openclaw  # dir containing package.json with name \"openclaw\"","handlingStrategy":"fallback","validationCode":"const root = process.env.OPENCLAW_ROOT ?? path.resolve('node_modules/openclaw');\nif (!fsSync.existsSync(path.join(root, 'package.json'))) { logger.error('openclaw root missing; run pnpm build or set OPENCLAW_ROOT'); }","typeGuard":null,"tryCatchPattern":"try { const run = await loadRunEmbeddedPiAgent(logger); } catch (e) { if (/Unable to resolve OpenClaw root/.test(e.message)) { logger.error('Set OPENCLAW_ROOT or run pnpm build'); process.exitCode = 1; } else throw e; }","preventionTips":["Set OPENCLAW_ROOT explicitly in deployment env/config","Always build the openclaw package in CI before running services","Verify the package root exists in your container/entrypoint startup checks"],"tags":["env","module-resolution","build"],"backgroundTag":"missing-package-root","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}