docs(rca): RCA for LiteLLM-internal spend tags leaking into Bedrock passthrough body

[mateo-berri]

Relevant issues

Root cause and primary report: #30629. Same symptom class, fixed route by route over time: #24661 (merged, /chat/completions), #27262 (open, /v1/messages). Generalized hardening already requested in #30301. In-flight fixes for #30629: #30985 (key-level, open) and #30994 (header-level, closed as superseded).

Linear ticket

N/A

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

This PR adds a single documentation file and changes no runtime code, so unit tests and a fix proof do not apply. The doc itself is the deliverable.

CI (LiteLLM team)

• Branch creation CI run
  Link:
• CI run for the last commit
  Link:
• Merge / cherry-pick CI run
  Links:

Screenshots / Proof of Fix

Not applicable. This PR introduces no behavior change; it adds docs/rca/2026-06-22-litellm-internal-tags-leak-into-bedrock-passthrough.md, a root-cause analysis. Every code claim in the doc cites the exact file:line it refers to, and the two type-checker guarantees in the prevention section were verified locally with pyright (a basedpyright-compatible fork), which reports reportIndexIssue on Mapping.__setitem__ and reportReturnType when a closed metadata TypedDict is built with an extra tags key.

Type

📖 Documentation

Changes

Adds an RCA for the class of bug where LiteLLM-internal spend tags get merged into the request metadata in place and then forwarded verbatim by the Bedrock invoke/converse passthrough route, which AWS rejects with metadata.tags: Extra inputs are not permitted (#30629).

The doc covers the root cause (one untyped dict serving as both internal request data and the provider-facing body, compounded by the cached-body accessor sharing nested objects by reference so an in-place merge aliases into the forwarded payload), a dated timeline showing the category being patched route by route rather than structurally, and a prevention section that makes the whole category fail at type-check or lint time rather than at runtime.

The prevention argument is the point of the doc. Typing the parsed body as an immutable Mapping turns every in-place tag merge into a basedpyright error and neutralizes the shared-reference footgun; giving LiteLLM-internal data a distinct type from the provider-facing body makes "forward internal data" a type error at a single projection boundary that replaces the allow-by-omission filter_internal_params(); and closing the provider metadata schema where it is known-closed (Anthropic on Bedrock allows user_id only) catches the missing-strip variant that #30301 tracks. It also explains why this category reaches a foolproof guarantee that the earlier stream_chunk_size RCA could not reach for its case, since the footgun here is shared-state mutation rather than open-key classification, and so does not require giving up passthrough.

[greptile-apps]

Greptile Summary

This PR adds a single RCA document (docs/rca/2026-06-22-litellm-internal-tags-leak-into-bedrock-passthrough.md) tracing the root cause of LiteLLM-internal spend tags leaking into Bedrock passthrough request bodies and proposing type-system-level prevention strategies. No runtime code is changed.

• The document provides a thorough root-cause analysis of the shared-mutable-dict footgun, a dated recurrence timeline, and a layered prevention proposal involving immutable Mapping types, a typed internal/provider boundary, and closed provider metadata schemas.
• The entire file should be placed in the litellm-docs repository rather than this one, per the project's documentation-placement rule.

Confidence Score: 3/5

The change is a documentation-only addition with no runtime impact, but the file is placed in the wrong repository.

The only changed file is a Markdown document. The content is technically accurate and internally consistent, but the project explicitly requires all documentation to live in the litellm-docs repository rather than here. Merging as-is would set a precedent for docs accumulating in this repo against the established policy.

docs/rca/2026-06-22-litellm-internal-tags-leak-into-bedrock-passthrough.md — should be moved to the litellm-docs repository.

Important Files Changed

Filename	Overview
docs/rca/2026-06-22-litellm-internal-tags-leak-into-bedrock-passthrough.md	New RCA document added to this repo, violating the project rule that documentation must live in the litellm-docs repository.

_{Reviews (1): Last reviewed commit: "docs(rca): RCA for LiteLLM-internal spen..." | Re-trigger Greptile}

[greptile-apps]

Documentation belongs in the litellm-docs repo

This repository's review standards explicitly prohibit adding documentation here — all docs must live in the litellm-docs repository. This entire file should be moved there rather than merged into berriai/litellm.

Rule Used: Prevent documentation from being added - needs to ... (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[devin-ai-integration]

🚅 Hi, thanks for the PR! I'm Agent Shin, the automated triage bot for this repository. What's this and why am I getting it?

I read the description against our contribution rubric. Here's how it lined up:

What you got right:

• ✅ Linked a related GitHub issue
• ✅ Clear problem description
• ✅ Expected vs. actual behavior

What's still missing:

• end-to-end QA proof (screenshot, video, or real command output)

The PR has strong context via linked issues and a clear problem description with expected vs. actual behavior, but it explicitly says screenshots/proof are not applicable and provides no end-to-end QA evidence. Per triage rules, absence of QA proof means the PR fails.

If the description isn't updated in the next 24 hours, I'll auto-close this PR. That's not us saying we don't care about the change; we want the open-PR list to mirror what a maintainer can act on right now, so contributors don't get lost in a backlog. A closed PR is a soft "park this for later," not a rejection. Take your time; everything below still works after the close.

During the grace period: just update the PR description with the missing pieces. No need to ping me; I'll re-check on the next sweep and skip the auto-close if it now passes. See what counts as QA proof for the full rubric (a linked issue alone isn't enough; it covers context, not proof).

If the PR does get auto-closed in 24 hours, you still have easy recovery paths:

• Comment @agent-shin reconsider after updating the description. I'll re-evaluate and reopen the PR if it now passes.
• Comment @greptileai to request a fresh Greptile review; that still works even after the PR is closed, and a stronger score is one of the signals that lifts the PR back into the queue. So a low Greptile score isn't a blocker either.

Internal BerriAI contributors: this rubric doesn't apply to you; ping a maintainer.

(I'm an LLM, so I'm not infallible. If you think I got this wrong, ping a maintainer; they'll override me.)