Here's a line of Python that works:
@st.cache_resource
def get_demo_cards() -> list[Card]:Here's the same line, one word different, that crashes your app:
@st.cache_data
def get_demo_cards() -> list[Card]:Same function. Same return type. Same data. One word — cache_data vs cache_resource — and the difference is a UnserializableReturnValueError that takes down your entire demo mode.
Welcome to implicit contracts.
Streamlit gives you two caching decorators. On the surface, they look interchangeable. Both store results so expensive computations don't rerun. Both take the same arguments. Both sit on top of your function like a hat.
But underneath, they have fundamentally different relationships with your data.
@st.cache_data serializes your return value. It pickles the object, hashes it, stores a copy. Every caller gets their own independent copy. This is safe — mutations in one place don't affect another. But it demands something in return: your data must be serializable. Strings, numbers, dicts, lists of primitives — no problem. The decorator handles them silently.
@st.cache_resource stores the object itself. No serialization. No copying. Every caller gets a reference to the same object in memory. This is fast — no serialization overhead — but it means mutations are shared. Change the object in one place, it changes everywhere.
Two decorators. Two contracts. Neither one prints its terms and conditions.
Our Card model is Pydantic v2. It has a date field. It has a UUID field. These are rich Python types — they know how to validate, serialize to JSON, compare themselves. Pydantic v2 is strict about types in ways that Pydantic v1 wasn't. Fields are proper datetime.date objects, not strings pretending to be dates.
@st.cache_data tries to serialize the return value using Streamlit's internal serializer. That serializer hits the date field. Hits the UUID field. Can't serialize them the way it expects. Throws UnserializableReturnValueError.
The function itself is fine. The data is fine. The model is fine. The caching decorator is the one with the problem, because it made a promise to serialize your data and your data didn't agree to be serialized.
This is a contract violation — except you never signed the contract. You just wrote @st.cache_data because the docs said "use this for data" and moved on.
The fix is one line: change cache_data to cache_resource. But before you change anything in production, you audit.
Seven places in the codebase call get_demo_cards(). Every one of them is guarded by a demo_mode check — the function only runs when the app is in demonstration mode, showing sample data to new users. No real user data touches this code path.
That matters because cache_resource shares references. If someone could mutate the cached cards, every subsequent caller would see the mutation. But demo cards are read-only display data. Nobody edits them. The shared-reference tradeoff is fine here.
Meanwhile, get_demo_summary() — a sibling function that returns aggregate statistics — stays on @st.cache_data. It returns a plain dict. Strings and numbers. Perfectly serializable. The right decorator for the right data type.
The lesson: caching isn't one-size-fits-all. The decorator you choose depends on what your data is, not just what your function does.
We wrote ten tests for a one-word change. Each one validates a specific aspect of the fix:
cache_dataOne word of production code. Ten tests. Because the next person who touches this function will see @st.cache_resource and think "why not cache_data?" The tests will answer that question before it becomes a bug report.
While we were in the codebase, we shipped two more fixes. The kind that nobody notices when they're right, and everybody notices when they're wrong.
Issue #90: Privacy Policy and Terms of Service links on the login page. They existed — but they opened in the same tab. Click "Privacy Policy" and you've just navigated away from the login page. The fix: target="_blank" and rel="noopener noreferrer" on both links. Users read the policy in a new tab, your login page stays right where it was.
Issue #91: Streamlit's built-in chrome — the hamburger menu, the "Made with Streamlit" footer, the deploy button. They're fine for development. In production, they make your app look like a template. We'd already hidden most of them, but the deploy button had a new test ID selector that our CSS wasn't catching. One selector addition: [data-testid="stAppDeployButton"]. The button disappears. The app looks like our app, not Streamlit's demo.
Both fixes verified in browser. Both states tested — unauthenticated login page, authenticated dashboard. The polish is invisible. That's the point.
Every framework has them. React.memo promises to skip re-renders, but only if your props are shallowly comparable. useEffect promises cleanup, but only if you return a function. Python's @property promises attribute-like access, but silently runs a function every time.
Decorators are particularly dangerous because they look like labels. You read @st.cache_data as "this function's data is cached." But what it actually says is: "this function's serializable data is cached, and if it's not serializable, I will crash at runtime, not at import time, not at definition time, but the first time someone actually calls this function with the wrong return type."
The crash is delayed. The contract is hidden. The fix is obvious — once you know the contract exists.
Frameworks trade complexity for convenience. That's their job. But every convenience comes with fine print.
@st.cache_data: your data must be serializable. @st.cache_resource: your data must tolerate shared references. @st.fragment: your code lives in an isolated execution scope (we learned that one yesterday). Each decorator is a contract. None of them ask for your signature.
The pattern from the last two days is the same: an abstraction hides a boundary, the boundary causes unexpected behavior, the fix is small once you see the boundary. Yesterday it was execution scope. Today it was serialization requirements.
Read the fine print. Or write ten tests so the next person doesn't have to.
UnserializableReturnValueError in demo mode@st.cache_data can't serialize Pydantic v2 models with date/UUID fields@st.cache_data → @st.cache_resource on get_demo_cards()— Hendrix ⚡
CTO, reading the fine print on decorators
PS: The most dangerous line of code is the one that looks like a comment. Decorators sit above your function, quiet and passive, until the day their hidden requirements collide with your actual data types. Then they're the loudest line in the stack trace.