{"record":{"id":"409591381331725d","repo":"JuliusBrussee/caveman","slug":"caveman-build-unresolved-source-dependency-json","errorCode":null,"errorMessage":"caveman build: unresolved source dependency ${JSON.stringify(specifier)}","messagePattern":"caveman build: unresolved source dependency (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/source-graph.ts","lineNumber":57,"sourceCode":"      ...esmSourceSpecifiers(typescript.lexableSource, path),\n      ...typescript.specifiers,\n      ...legacySourceSpecifiers(source, path, code),\n    ]);\n    for (const specifier of specifiers) {\n      if (BUILTINS.has(specifier)) continue;\n      const bare = !specifier.startsWith(\".\");\n      if (bare && !includeBareDependencies) continue;\n      let base: string;\n      let packageRoot: string | undefined;\n      if (bare) {\n        packageRoot = dependencyPackageRoot(specifier, path);\n        try {\n          base = createRequire(path).resolve(specifier);\n        } catch (requireError) {\n          try {\n            base = await resolveImportOnlyDependency(specifier, path);\n          } catch {\n            throw new Error(\n              `caveman build: unresolved source dependency ${JSON.stringify(specifier)}`,\n              { cause: requireError },\n            );\n          }\n        }\n      } else {\n        base = resolve(dirname(path), specifier);\n      }\n      const candidates = extname(base)\n        ? explicitImportCandidates(base, path)\n        : [\n          base,\n          ...RESOLUTION_EXTENSIONS.map((extension) => base + extension),\n          ...SOURCE_EXTENSIONS.map((extension) => resolve(base, `index${extension}`)),\n        ];\n      let found: string | undefined;\n      for (const candidate of candidates) {\n        try {","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/source-graph.ts#L39-L75","documentation":"During 'caveman build' the source-graph walker resolves bare (package) import specifiers to files on disk. It first tries Node's createRequire().resolve, then a fallback resolver for import-only dependencies; if both fail, the dependency cannot be traced to source and this error is thrown with the specifier quoted and the original require error as cause.","triggerScenarios":"expandSourceGraph (via sourceFiles/graph/files) encounters a bare specifier whose package cannot be resolved from the importing file's path — package not installed, export map hides the entry, or monorepo workspace not linked.","commonSituations":"Forgetting 'npm/pnpm install' after adding a dependency; workspace package not linked in a monorepo; dependency only importable at runtime (bundled/aliased) so Node resolution fails; typos in the import specifier.","solutions":["Install the missing dependency (npm/pnpm install) so createRequire can resolve it","If it's a workspace package, link it properly (workspaces config / pnpm link) or build its dist output","Check package.json 'exports' of the dependency — a specifier pointing to a non-exported subpath will fail resolution","Verify the specifier spelling against the actual package name"],"exampleFix":"// before\nimport { helper } from '@acme/utils';   // not installed\n// after\n$ npm install @acme/utils\nimport { helper } from '@acme/utils';","handlingStrategy":"validation","validationCode":"import { createRequire } from 'module';\ntry {\n  createRequire(importerPath).resolve(specifier);\n} catch {\n  throw new Error(`Install missing dependency: ${specifier}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await build({ files: sourceFiles(entry) });\n} catch (e) {\n  const m = /unresolved source dependency (.+)/.exec(e.message);\n  if (m) console.error(`npm install ${JSON.parse(m[1])}`);\n  else throw e;\n}","preventionTips":["Run npm/pnpm install before builds (CI: cache + install step)","Keep monorepo workspace links consistent","Validate import specifiers with a linter (no unresolved imports)"],"tags":["build","module-resolution","dependencies"],"backgroundTag":"missing-dependency","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}