paperclipai/paperclip · error

Attachment-backed artifact metadata is required

Error message

Attachment-backed artifact metadata is required

What it means

422 on work product update. Fires when the patch would leave an attachment-backed (paperclip) artifact without required attachment metadata: metadata is absent from the patch and the existing record does not already satisfy the paperclip attachment metadata requirements, so the update is rejected.

Source

Thrown at server/src/routes/issues.ts:8412

        actorId: actor.actorId,
        agentId: actor.agentId,
        runId: actor.runId,
        agentApiKeyId: actor.agentApiKeyId,
        action: "issue.document_unlocked",
        entityType: "issue",
        entityId: issue.id,
        details: {
          key: result.document.key,
          documentId: result.document.id,
          title: result.document.title,
        },
      });
    }

    res.json(result.document);
  });

  router.get("/issues/:id/documents/:key/revisions", async (req, res) => {
    const id = req.params.id as string;
    const issue = await getAccessibleResource(req, res, getIssueById(req, id), "Issue not found");
    if (!issue) return;
    if (!(await assertIssueReadAllowed(req, res, issue))) return;
    const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
    if (!keyParsed.success) {
      res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
      return;
    }
    const revisions = await documentsSvc.listIssueDocumentRevisions(issue.id, keyParsed.data);
    res.json(revisions);
  });

  router.post(
    "/issues/:id/documents/:key/revisions/:revisionId/restore",
    validate(restoreIssueDocumentRevisionSchema),
    async (req, res) => {
      const id = req.params.id as string;

View on GitHub (pinned to 01ad858492)

Solutions

1. Include the required field(s) in the request path, query, or body as named by the error message, then retry.
2. Check the API contract in packages/shared validators for the exact required shape of this endpoint.

When it happens

Trigger: Thrown at server/src/routes/issues.ts:7825 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-08-18). Data as JSON: /api/errors/a4bb8567480f51a5. Report an issue: GitHub.