{"record":{"id":"6bb0a1b4edeb27af","repo":"paperclipai/paperclip","slug":"paperclip-runner-file-handoff-workspace-unavailable","errorCode":"paperclip_runner_file_handoff_workspace_unavailable","errorMessage":"paperclip_runner_file_handoff_workspace_unavailable","messagePattern":"paperclip_runner_file_handoff_workspace_unavailable","errorType":"error_code","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"server/src/services/native-runtime/paperclip-runner-tool-authority.ts","lineNumber":923,"sourceCode":"        blockedByIssueIds,\n        actorAgentId: this.binding.agentId,\n      }, tx);\n      if (!updated) throw new Error(\"paperclip_runner_task_not_found\");\n      return {\n        commandId: `set-dependencies:${updated.id}:${updated.statusVersion}`,\n        disposition: \"applied\",\n        stateRevision: updated.statusVersion,\n        entityRefs: [updated.id, ...blockedByIssueIds],\n        scheduledWakeIds: [],\n      };\n    });\n  }\n\n  async #registerDeliverable(input: Record<string, unknown>): Promise<unknown> {\n    const idempotencyKey = requiredString(input.idempotencyKey);\n    const workspaceRoot = this.binding.workspaceRoot?.trim();\n    if (!workspaceRoot) {\n      throw new Error(\"paperclip_runner_file_handoff_workspace_unavailable\");\n    }\n    let publication:\n      Awaited<ReturnType<typeof persistActivity>>[\"publication\"] | null = null;\n    let rollbackDefinitePreCommitFailure: (() => Promise<void>) | null = null;\n    const result = await this.#withMutationReceipt(\n      \"register_deliverable\",\n      idempotencyKey,\n      input,\n      async (tx, context) => {\n        const prepared = await prepareNativeRunnerFileHandoff({\n          db: tx,\n          binding: {\n            companyId: this.binding.companyId,\n            issueId: this.binding.issueId,\n            runId: this.binding.runId,\n            agentId: this.binding.agentId,\n            workspaceRoot,\n            executionTargetKind: this.binding.executionTargetKind ?? \"local\",","sourceCodeStart":905,"sourceCodeEnd":941,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/server/src/services/native-runtime/paperclip-runner-tool-authority.ts#L905-L941","documentation":"Thrown at the start of #registerDeliverable when the run's binding has no workspaceRoot (or it is empty after trim). Registering a deliverable requires a file handoff workspace to persist the artifact, so without a bound workspace the tool refuses immediately with this sentinel error code.","triggerScenarios":"Calling the register_deliverable runner tool from a run whose binding.workspaceRoot is undefined/empty — e.g. API-driven or remote runs created without a workspace, or adapters that do not clone a repo workspace.","commonSituations":"Runs launched in headless/no-checkout mode, misconfigured native runtime that omits workspaceRoot in the binding, environments where the workspace was cleaned up before the run reported its deliverable.","solutions":["Ensure the run is created with a bound workspace so binding.workspaceRoot is populated before calling register_deliverable.","If the run intentionally has no workspace, use a different reporting path (e.g. report_progress with the artifact content) instead of file handoff.","Inspect the native runtime binding construction to confirm workspaceRoot is passed and not cleared by trim/normalization."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (!binding.workspaceRoot?.trim()) {\n  throw new Error('register_deliverable requires a workspace-bound run');\n}","typeGuard":"function hasWorkspace(b: { workspaceRoot?: string | null }): b is { workspaceRoot: string } {\n  return typeof b.workspaceRoot === 'string' && b.workspaceRoot.trim().length > 0;\n}","tryCatchPattern":null,"preventionTips":["Create runs with a bound workspace when file handoff is planned","Check binding.workspaceRoot at run startup and disable file tools if absent","Do not clean up workspace directories before deliverables are registered"],"tags":["workspace","file-handoff","runner-tools","configuration"],"backgroundTag":"missing-required-config-field","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}