{"record":{"id":"05f8aa6efc6fc2ad","repo":"paperclipai/paperclip","slug":"runner-local-provider-artifact-missing","errorCode":"runner_local_provider_artifact_missing","errorMessage":"runner_local_provider_artifact_missing: ${artifact} is absent; build @paperclipai/paperclip-runner TypeScript artifacts with build:typescript before starting a local JS-backed provider","messagePattern":"runner_local_provider_artifact_missing: (.+?) is absent; build @paperclipai/paperclip-runner TypeScript artifacts with build:typescript before starting a local JS-backed provider","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/live/runnerd-codex-transport.ts","lineNumber":2706,"sourceCode":"type BuildOwnedCliArtifact =\n  \"acpx-runtime-sidecar.cjs\" | \"opencode-app-server-proxy.cjs\";\n\nfunction buildOwnedCliArtifactCandidates(\n  artifact: BuildOwnedCliArtifact,\n): readonly string[] {\n  return [\n    fileURLToPath(new URL(`../cli/${artifact}`, import.meta.url)),\n    resolve(packageRoot, \"dist\", \"cli\", artifact),\n  ];\n}\n\nfunction resolveBuildOwnedCliArtifact(\n  artifact: BuildOwnedCliArtifact,\n  candidates: readonly string[] = buildOwnedCliArtifactCandidates(artifact),\n): string {\n  const resolved = candidates.find((candidate) => existsSync(candidate));\n  if (resolved) return resolved;\n  throw new Error(\n    `runner_local_provider_artifact_missing: ${artifact} is absent; build @paperclipai/paperclip-runner TypeScript artifacts with build:typescript before starting a local JS-backed provider`,\n  );\n}\n\nfunction acpxProviderPackageAuthority(\n  sidecarScript: string,\n  ownerPackageRoot = packageRoot,\n): {\n  root: string;\n  manifest: string;\n} {\n  const cliDirectory = dirname(sidecarScript);\n  if (\n    basename(sidecarScript) !== \"acpx-runtime-sidecar.cjs\" ||\n    basename(cliDirectory) !== \"cli\" ||\n    basename(dirname(cliDirectory)) !== \"dist\"\n  ) {\n    throw new Error(","sourceCodeStart":2688,"sourceCodeEnd":2724,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/live/runnerd-codex-transport.ts#L2688-L2724","documentation":"resolveBuildOwnedCliArtifact resolves a build-owned CLI artifact by checking candidate filesystem paths and throws when none exist. The runner requires TypeScript-built artifacts of @paperclipai/paperclip-runner (dist output) before starting a local JS-backed provider. The throw guarantees the runner never boots a provider against missing/stale source-only state.","triggerScenarios":"Calling code that starts a local JS-backed provider (via resolveBuildOwnedCliArtifact) when the runner package's TypeScript build output has never been produced or was deleted, so no candidate path exists.","commonSituations":"Fresh clone without running build:typescript; a clean that removed dist/; CI checkout skipping the build step; starting runnerd directly with tsx/node without a prior build; pnpm install pruning generated artifacts.","solutions":["Run the TypeScript build for the runner package: pnpm --filter @paperclipai/paperclip-runner build:typescript (or repo-level equivalent).","Verify the expected artifact (e.g. dist/cli/...) exists on disk before starting the provider.","If building in CI, add the build:typescript step to the job before the provider start step.","If the artifact should not be build-owned, point the provider at an installed/published package instead of the workspace source."],"exampleFix":"// before\nstartLocalProvider(); // throws: artifact absent\n// after\nexecSync('pnpm --filter @paperclipai/paperclip-runner build:typescript', { stdio: 'inherit' });\nstartLocalProvider();","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nif (!existsSync('node_modules/@paperclipai/paperclip-runner/dist/cli')) {\n  throw new Error('runner TypeScript artifacts missing; run build:typescript first');\n}","typeGuard":"const hasBuildArtifacts = (root: string): boolean => existsSync(join(root, 'dist'));","tryCatchPattern":"try {\n  startLocalProvider();\n} catch (err) {\n  if ((err as Error).message.includes('runner_local_provider_artifact_missing')) {\n    execSync('pnpm --filter @paperclipai/paperclip-runner build:typescript', { stdio: 'inherit' });\n    startLocalProvider();\n  } else throw err;\n}","preventionTips":["Always run build:typescript after install in dev and CI","Add a prestart/preboot hook that builds the runner package","Verify dist/ existence in health/startup checks"],"tags":["build","filesystem","runner","missing-artifact"],"backgroundTag":"file-not-found","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}