ERPNext v16 Custom Report Filter Bugs: The Shape Assumption That Breaks Them

I am Manoj, ERP implementation lead at Mith Tech in Bengaluru. Most of the "v16 broke our reports" tickets we see are not v16 breaking anything — they are a custom app that got away with a shape assumption for two years. Finally met a caller that did not honour it. The useful work is telling those two situations apart quickly, which means knowing exactly which release fixed what.

How do you use Start with the version question, because the answers differ?

The single most common mistake in the community threads on this topic is treating the three failures as one story with one fix. They are not. One is a shipped regression with a clean before-and-after release boundary. One is an open report that a maintainer disputes and that no one has reproduced on stock code. One never touched a v16 release at all.

Case 1 — the Delivery Note selector, and the only genuine v16 regression here

Issue #54805: using a filter in Sales Invoice's "Get Items From → Delivery Note" dialog throws a MariaDB 1064 syntax error, with a bracketed Python list visible in the error text.

It was introduced by PR #52594, commit ef454822d7bc. Read that PR's title and you will see the trap: it is about toggling a button based on is_return and POS view. The Query Builder rewrite of get_delivery_notes_to_be_billed rode along inside it. Grepping release notes for "query builder" would never have found this.

What the rewrite removed was the delegation to Frappe's own filter compiler:

fcond=get_filters_cond(doctype, filters, []),
mcond=get_match_cond(doctype),

What replaced it was a loop that assumes every filter is an equality:

if filters and isinstance(filters, dict):
    for key, value in filters.items():
        query = query.where(DeliveryNote[key] == value)

get_filters_cond understands the Frappe filter grammar — ["Between", [...]], [">", 1000], ["in", [...]], ["like", "%x%"]. The loop understands none of it. When the dialog sends {"posting_date": ["Between", null]}, that compiles to `posting_date` = ['Between', NULL] and MariaDB rejects it. get_match_cond was dropped in the same change, which is a permissions concern on top of a syntax one.

The fix is PR #55443, commit 4ef17c9, which deletes the loop and seeds the query from frappe.qb.get_query. We read erpnext/controllers/queries.py at each release tag to find the boundary: v16.14.0 through v16.20.1 carry the bug; v16.21.0 is the first fixed v16 release. On the v15 line, v15.110.0 is the first fixed release; we confirmed v15.109.3 still carries it.

One oddity worth knowing if you go read the issue: it was closed on 2026-05-28, three days before its fix merged on 2026-05-31. The visible context is a need-more-info label and a maintainer who could not reproduce it. Why it was closed early is not recorded anywhere in the timeline, and we are not going to guess.

Case 2 — the Stock Balance crash that your Stock Balance report almost certainly does not have

Issue #57212 reports AttributeError: 'str' object has no attribute 'nodes_' from Stock Balance when item_code is a single string. It is open, and it is disputed — and the dispute is the interesting part.

The unguarded line is real. erpnext/stock/report/stock_balance/stock_balance.py line 451, identical on develop and version-16 today:

if item_codes := self.filters.get("item_code"):
    query = query.where(item_table.name.isin(item_codes))

pypika's ContainsCriterion.nodes_() does yield from self.container.nodes_(). Hand it a str and you get an AttributeError whose traceback mentions pypika, your report, and nothing about the filter that caused it.

But a maintainer's rebuttal on the issue is correct, and we verified it independently: upstream stock_balance.js declares item_code as a MultiSelectList on both develop and version-16. The stock report UI cannot emit a bare string. So the crash is reachable only when the report is invoked programmatically (frappe.desk.query_report.run with filters={"item_code": "Melamine"}), when a Client Script or app override has downgraded the filter to a Link, or when a custom app constructs the report class directly with a scalar.

If you only ever run Stock Balance from the desk, this cannot reach you. If your app, your scheduled job, or your integration calls it, normalise on your side — there is no fix PR,. No one has reproduced it on stock code, us included.

What makes it worth studying anyway is what sits one directory away. erpnext/stock/report/stock_ledger/stock_ledger.py guards the same class of value in four separate places, including the exact branch that stock_balance.py is missing:

if isinstance(value, list | tuple):
    query = query.where(table[field].isin(value))
else:
    query = query.where(table[field] == value)

and a scalar-to-list normalisation at the top of the function:

item_codes = filters.item_code
if isinstance(item_codes, str):
    item_codes = [item_codes]

Same app, same project, same conventions. One file survives a scalar; the other does not.

{"item_code": "Melamine"}

query = query.where(item_table.name.isin(item_codes))

AttributeError: 'str' object has no attribute 'nodes_'

if isinstance(value, list | tuple):
    query = query.where(table[field].isin(value))
else:
    query = query.where(table[field] == value)

item_codes = filters.item_code
if isinstance(item_codes, str):
    item_codes = [item_codes]

Case 3 — the Python 3.14 annotation trap, which is the shape of things coming in v17

Issue #56657: adding an item to a Sales Invoice raised FrappeTypeError: Argument 'ctx' in 'erpnext.stock.get_item_details.apply_price_list' should be of type 'frappe.types.frappedict._dict | str' but got 'dict' instead.

The root cause is genuinely a Python 3.14 language change, and ERPNext's own commit message states it precisely. PEP 649/749 replaced __annotations__ with __annotate__ in functools.WRAPPER_ASSIGNMENTS. ERPNext's normalize_ctx_input decorator excluded only __annotations__ when wrapping:

@functools.wraps(func, assigned=(a for a in functools.WRAPPER_ASSIGNMENTS if a != "__annotations__"))
def wrapper(ctx: T | Document | dict | str, *args, **kwargs): ...

So functools.wraps copied the wrapped function's __annotate__, and the wrapper's permissive _dict | Document | dict | str annotation was silently replaced by the narrow ItemDetailsCtx | str. The decorator's runtime body already handled a plain dict correctly — but frappe.utils.typing_validations reads the annotation before the body runs. Pydantic validates frappe._dict as an arbitrary type, meaning isinstance with no coercion, and a plain dict is not an instance of the frappe._dict subclass. The call never reached the code that would have normalised it.

The fix adds __annotate__ to the exclusion list. It landed on develop only, via commits 6eeadbd, f26cb79, 9406ec4 and 5956d3e — there is no linked PR; the issue was closed with a comment and we located the commits by scanning the file's history in the closing window.

Now the scope, which is the part that gets misreported: apply_price_list on version-16 is def apply_price_list(ctx, as_doc=False, doc=None) — no argument annotations at all. typing_validations only checks parameters that carry annotations, so there is nothing to enforce and this error cannot fire there. develop is v17, not v16. No shipped v16 release is affected by this issue.

Treat it as a preview. The __annotate__ trap itself is a plain Python 3.14 behaviour, so if your app wraps annotated functions with functools.wraps, you can reproduce the same silent annotation swap in your own code today. And the follow-up commits read like a checklist of the same mistake: restoring | dict on helper signatures plus the frappe._dict(pctx) coercion inside the body, reserving the narrow type for the normalisation boundary only, and fixing a cts=args keyword typo that had sat in transaction_base.py unnoticed until type checking made it visible.

What we verified, and what we did not

We read the source at release tags and used the GitHub compare API to confirm ancestry — that is where every version boundary in this post comes from. We read the issue timelines, the PR diffs, the commit messages, and the current state of stock_balance.py, stock_ledger.py, queries.py and stock_balance.js on both develop and version-16.

We did not reproduce any of these on a live bench. We did not reproduce #57212 on stock code — nobody has. Two of the three issues were reported from Frappe Cloud benches, and Frappe Cloud's patch state relative to public tags is opaque to us, so every version window here is for the public GitHub release tags only. Where the record is silent — the early closure of #54805, the missing PR link on #56657 — we have said so rather than filled the gap.

The one sentence that unifies all three

Each of these is code that assumed a filter or argument value would arrive in one particular shape, at a boundary where the framework stopped guaranteeing that shape.

• #54805 assumed filter values are scalars. They can be ["Between", [...]].
• #57212 assumed item_code is a sequence. It can be a str.
• #56657 assumed ctx is a frappe._dict. It can be a plain dict.

Those assumptions used to be absorbed by something. Raw SQL had get_filters_cond doing the parsing. Form-encoded request bodies stringified everything, so a dict and a JSON string of a dict were the same thing on arrival. Unannotated signatures meant no validator ever looked. The migration from frappe.db.sql to frappe.qb removes the first cushion. The v17 move to JSON request bodies and enforced annotations removes the other two. v16 is the release where the cushions are thinning but the enforcement has not arrived — which makes it the cheapest possible time to fix your shape assumptions.

How do you audit your own instance?

# Pre-upgrade audit for filter-shape assumptions
# Run from your bench root, against apps/

# 1. .isin() on a value that is not obviously a literal list
#    -> the erpnext#57212 class (stock_balance.py:451)
grep -rn "\.isin(" apps/ --include=*.py | grep -v "isin(\["

# 2. Hand-rolled filter loops over frappe.qb
#    -> the erpnext#54805 class (the v16.14.0-v16.20.1 regression)
grep -rn -A3 "for key, value in filters.items()" apps/ --include=*.py
grep -rn -B2 -A6 "frappe.qb.from_" apps/ --include=*.py | grep -n "filters"

# 3. Raw SQL still using the old filter compilers. These are the call
#    sites that WILL break if someone "modernises" them to qb.
grep -rn "get_filters_cond\|get_match_cond" apps/ --include=*.py

# 4. Attribute access on a filters/args dict
#    -> the commit c286a73e0b88 class (frappe._dict vs plain dict)
grep -rnE "\bfilters\.[a-z_]+\b" apps/ --include=*.py \
  | grep -v "filters\.get\|filters\.items\|filters\.keys\|filters\.values\|filters\.update\|filters\.pop"
grep -rnE "\bargs\.[a-z_]+\b" apps/ --include=*.py \
  | grep -v "args\.get\|args\.items\|args\.update\|args\.pop"

# 5. functools.wraps on Python 3.14
#    -> the PEP 649 / __annotate__ class behind erpnext#56657
grep -rn "functools.wraps\|from functools import wraps" apps/ --include=*.py
grep -rn "WRAPPER_ASSIGNMENTS" apps/ --include=*.py   # any hit needs __annotate__

# 6. Report .js filters whose fieldtype you changed
#    -> the erpnext#57212 dispute: MultiSelectList and Link are not
#       interchangeable, because the Python side does .isin()
grep -rn "fieldtype: \"MultiSelectList\"\|fieldtype: \"Link\"" apps/ --include=*.js \
  | grep -i "report"

What are the three cases side by side?

How do you At a glance — quick reference?

Frequently asked questions

Is it safe to replace frappe.db.sql with frappe.qb in my custom app?. Only if you replace the filter compilation too. frappe.db.sql calls typically pass filters through get_filters_cond and permissions through get_match_cond. Writing frappe.qb.from_(X).where(X[k] == v) in a loop reproduces neither — that is exactly what shipped in v16.14.0 and broke the Delivery Note selector. Use frappe.qb.get_query(doctype, fields=..., filters=..., ignore_permissions=False), which parses the filter grammar and re-applies user permissions, then add your own hard conditions on top.

Hey Google, what happens if we do not fix filter shape assumptions before upgrading ERPNext?. Nothing, until a caller changes. Then a scheduled job fails at 2am with an AttributeError from inside pypika, or a link-field dialog throws a MariaDB 1064 with a Python list visible in the SQL, and the traceback names none of your code. The failures are intermittent because they depend on what shape a particular caller happened to send, which makes them expensive to diagnose under pressure. The audit takes an afternoon; the same bug found during month-end close takes a day and costs you trust.

None of this is exotic. It is the ordinary cost of a framework tightening its contracts while a decade of application code carries assumptions those contracts used to hide. The version work is an afternoon and closes exactly one of the three cases. The rest is a grep, a normalisation helper, and one rehearsal on a scratch site. Do it while nobody is waiting on the answer. If you would rather not do it yourself, that is roughly what our ERPNext implementation and support work looks like on an upgrade.