{"record":{"id":"cc425e9a8a273bdf","repo":"paperclipai/paperclip","slug":"paperclip-runner-chat-attachment-remote-staging-unsupported","errorCode":"paperclip_runner_chat_attachment_remote_staging_unsupported","errorMessage":"paperclip_runner_chat_attachment_remote_staging_unsupported","messagePattern":"paperclip_runner_chat_attachment_remote_staging_unsupported","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/src/services/native-runtime/chat-attachment-read.ts","lineNumber":82,"sourceCode":"    if (this.#closed)\n      throw new Error(\"paperclip_runner_chat_attachment_read_scope_closed\");\n  }\n\n  read(input: { sourceCommentId: string; attachmentId: string }) {\n    this.#assertOpen();\n    if (\n      !UUID.test(input.sourceCommentId) ||\n      !UUID.test(input.attachmentId) ||\n      Object.keys(input).some(\n        (key) => key !== \"sourceCommentId\" && key !== \"attachmentId\",\n      )\n    ) {\n      throw new Error(\n        \"paperclip_runner_chat_attachment_read_arguments_invalid\",\n      );\n    }\n    if (this.options.executionTargetKind !== \"local\") {\n      throw new Error(\n        \"paperclip_runner_chat_attachment_remote_staging_unsupported\",\n      );\n    }\n    if (++this.#readCount > 20)\n      throw new Error(\"paperclip_runner_chat_attachment_read_limit\");\n    const pending = this.#read(input);\n    this.#pending.add(pending);\n    void pending\n      .finally(() => this.#pending.delete(pending))\n      .catch(() => undefined);\n    return pending;\n  }\n\n  async #authorized(input: {\n    sourceCommentId: string;\n    attachmentId: string;\n  }): Promise<ChatAttachmentReuseSource> {\n    // Run-event persistence also briefly locks heartbeat_runs. A NOWAIT miss","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/server/src/services/native-runtime/chat-attachment-read.ts#L64-L100","documentation":"Staging attachment bytes into a temporary workspace path is only implemented for locally-executed runs. When the scope was constructed with executionTargetKind \"remote\", read() refuses immediately with this error because the workspace-file handoff cannot reach a remote execution target.","triggerScenarios":"Calling read() on a scope whose options.executionTargetKind is \"remote\"; configuring the native runner with a remote execution target while still advertising the read_chat_attachment tool to the agent.","commonSituations":"Deploying runs to a remote sandbox/executor without porting the local staging path; a feature gap where remote runtimes were added before this tool was remote-capable.","solutions":["Run the agent on a local execution target if it needs read_chat_attachment.","Do not expose READ_CHAT_ATTACHMENT_TOOL_DEFINITION in the tool set for remote execution targets.","Implement remote staging in native-runner-file-handoff if remote support is required upstream.","Route the attachment read through the remote executor's own file API as a fallback."],"exampleFix":"// before\nnew NativeChatAttachmentReadScope({ ..., executionTargetKind: \"remote\" });\n// after\nnew NativeChatAttachmentReadScope({ ..., executionTargetKind: \"local\" });","handlingStrategy":"validation","validationCode":"if (scope.options.executionTargetKind !== \"local\") {\n  throw new Error(\"read_chat_attachment requires a local execution target\");\n}","typeGuard":"function supportsAttachmentRead(scope: { options: { executionTargetKind: string } }): boolean {\n  return scope.options.executionTargetKind === \"local\";\n}","tryCatchPattern":"try {\n  const file = await scope.read(input);\n} catch (e) {\n  if (e.message === \"paperclip_runner_chat_attachment_remote_staging_unsupported\") return null; // feature unavailable\n  throw e;\n}","preventionTips":["Gate the read_chat_attachment tool definition on executionTargetKind === \"local\".","Only create read scopes for local runs.","Document the local-only limitation in tool listing for remote runtimes.","Add a remote staging implementation before enabling the tool remotely."],"tags":["unsupported","remote-execution","staging"],"backgroundTag":"unsupported-operation","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}