Skip to content

feat(uploads): Restrict attachment type #17229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jjbayer wants to merge 2 commits into
base: master
Choose a base branch
from
Open

feat(uploads): Restrict attachment type #17229

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3724e73
feat(uploads): Restrict attachment type
jjbayer Apr 2, 2026
c5074df
fix link
jjbayer Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions develop-docs/sdk/telemetry/attachments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ Trace attachments use item type `"attachment"` with content type `"application/v
### Attachment Placeholders

<Alert level="warning">
Attachment placeholders are an experimental feature, the protocol is subject to change.
Attachment placeholders are an experimental feature, the protocol is subject to change and requires the feature `projects:relay-upload-endpoint` enabled on the server.
</Alert>

Attachment placeholders use item type `"attachment"` with content type `"application/vnd.sentry.attachment-ref+json"`. A placeholder contains a **reference** to an attachment uploaded elsewhere — it does _not_ contain the actual attachment payload. The purpose is for the attachment to be handled (rate limited, filtered, etc.) together with the event payload, even if it was uploaded separately.
Expand All @@ -184,7 +184,7 @@ SDKs **SHOULD** send placeholders in the same envelope as the event the file is

**Workflow:**

1. If an attachment is larger than ~100 MiB, upload it to the [TUS](https://tus.io/protocols/resumable-upload#creation-with-upload)-conformant upload endpoint (requires feature `projects:relay-upload-endpoint`):
1. If an attachment is larger than ~100 MiB and does not require special processing (that is, it has [attachment type `event.attachment`](#attachment-types)), upload it to the [TUS](https://tus.io/protocols/resumable-upload#creation-with-upload)-conformant upload endpoint:
1. Create the upload:
```shell
curl -X POST https://o0.ingest.sentry.io/api/0/upload/ \
Expand Down Expand Up @@ -251,11 +251,12 @@ SDKs **SHOULD** send placeholders in the same envelope as the event the file is
|-------|------|----------|-------------|
| `type` | String | **REQUIRED** | **MUST** be `"attachment"`. |
| `content_type` | String | **REQUIRED** | **MUST** be `"application/vnd.sentry.attachment-ref+json"`. |
| `attachment_type` | String | **REQUIRED** | **MUST** be `event.attachment` (no special processing). |
Copy link
Copy Markdown

@sentry sentry bot Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The documentation for attachment placeholders is contradictory. The attachment_type field is marked as REQUIRED in one place but is described as conditional and omitted from an example elsewhere.
Severity: MEDIUM

Suggested Fix

Update the documentation to be consistent. The prose on line 259 should be changed to state that attachment_type is always required. The JSON example on line 391 should be updated to include the "attachment_type":"event.attachment" field to match the specification.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: develop-docs/sdk/telemetry/attachments.mdx#L254

Potential issue: The documentation for attachment placeholders in
`develop-docs/sdk/telemetry/attachments.mdx` contains conflicting information regarding
the `attachment_type` field. A newly added table on line 254 specifies that
`attachment_type` is a `REQUIRED` field. However, pre-existing prose on line 259 implies
it is conditional, stating it should be included "if it was set". Furthermore, an
example envelope on line 391 omits the `attachment_type` field entirely. This
contradictory guidance will likely lead to inconsistent SDK implementations, with some
treating the field as required, some as conditional, and others as optional, undermining
protocol compliance.

Did we get this right? 👍 / 👎 to inform future reviews.

| `length` | Integer | **REQUIRED** | Size of the placeholder payload in bytes. |
| `attachment_length` | Integer | **REQUIRED** | Size of the referenced attachment in bytes. |
| `filename` | String | **REQUIRED** | The name of the uploaded file without a path component. |

The item header **MUST** also contain the original file's `attachment_type` if it was set. The item payload **MUST** contain the original file's `content_type` as a field in the JSON object (see [Standard Attachment Item](#standard-attachment-item)).
For attachment placeholders, the `attachment_type` **MUST** be `event.attachment`. Other attachment types cannot be uploaded via the [upload endpoint](#attachment-placeholders) because they require [special processing](#attachment-types), which the upload endpoint bypasses. The item header **MUST** also contain the original file's `attachment_type` if it was set. The item payload **MUST** contain the original file's `content_type` as a field in the JSON object (see [Standard Attachment Item](#standard-attachment-item)).

**Item payload:**

Expand Down
Loading