Draft docs in ERPNext 'Get Items From' dropdowns — the client-script filter that fixes it

The picker and the mapper are two different guards. When they disagree, users see phantom bugs. I am Manoj, ERPNext and Frappe implementation lead at MithTech in Bengaluru — this is one of the most frequently misfiled tickets we inherit from teams migrating off Tally.

The two guards that must agree

The picker and the mapper are enforced in two entirely different files, by two entirely different mechanisms, and they can drift independently. That's the whole bug.

get_query_filters: {
  docstatus: 1,
  status: ["not in", ["Closed"]],
  company: me.frm.doc.company,
}

"Purchase Receipt": {
  "doctype": "Purchase Invoice",
  "validation": {
    "docstatus": ["=", 1]
  },
}

Cannot map because
following condition
fails: docstatus=1

The UI list query lives in the source form's JS

Every ERPNext form that offers a "Get Items From" button calls erpnext.utils.map_current_doc with a get_query_filters dict. That dict is handed to a MultiSelectDialog which renders the picker. If docstatus: 1 is present in the dict, drafts never reach the list.

You can see this in erpnext/public/js/utils.js around line 1095, where the utility hands get_query_filters to the dialog's get_query:

let query_args = {};
if (opts.get_query_filters) {
    query_args.filters = opts.get_query_filters;
}
if (opts.get_query_method) {
    query_args.query = opts.get_query_method;
}
if (query_args.filters || query_args.query) {
    opts.get_query = () => JSON.parse(JSON.stringify(query_args));
}

Every caller — purchase_invoice.js, purchase_order.js, sales_order.js, quotation.js, supplier_quotation.js — is expected to populate get_query_filters with docstatus: 1 themselves. Most do. Some don't. The ones that don't produce the bug.

For example, the Purchase Invoice caller in erpnext/accounts/doctype/purchase_invoice/purchase_invoice.js around line 191 gets it right:

erpnext.utils.map_current_doc({
    method: "erpnext.stock.doctype.purchase_receipt.purchase_receipt.make_purchase_invoice",
    source_doctype: "Purchase Receipt",
    target: me.frm,
    get_query_filters: {
        docstatus: 1,
        status: ["not in", ["Closed", "Completed", "Return Issued"]],
        company: me.frm.doc.company,
        is_return: 0,
    },
    // ...
});

But this is a per-call convention, not a framework guarantee. A single caller (custom or upstream) that omits docstatus: 1 and the picker leaks drafts.

The backend validator lives in the mapper

Meanwhile, frappe.model.mapper.get_mapped_doc reads a per-map-config validation dict and throws before mapping if the source's field values don't match. From frappe/model/mapper.py:170:

def map_doc(source_doc, target_doc, table_map, source_parent=None):
    if table_map.get("validation"):
        for key, condition in table_map["validation"].items():
            if condition[0] == "=" and source_doc.get(key) != condition[1]:
                frappe.throw(
                    _("Cannot map because following condition fails:") + f" {key}={cstr(condition[1])}"
                )

And every mapper in ERPNext core does declare it. Take erpnext/stock/doctype/purchase_receipt/purchase_receipt.py:1572, the make_purchase_invoice mapper:

doclist = get_mapped_doc(
    "Purchase Receipt",
    source_name,
    {
        "Purchase Receipt": {
            "doctype": "Purchase Invoice",
            "field_map": { ... },
            "validation": {
                "docstatus": ["=", 1],
            },
        },
        # ...
    },
    target_doc,
    set_missing_values,
)

The validation block is doing exactly what it should: rejecting a draft source before mapping. The problem is only that the rejection message reaches the user after the picker has offered them the draft — which is precisely when it feels like a bug.

Same shape in erpnext/selling/doctype/sales_order/sales_order.py:1171 for the make_delivery_note mapper, at line 1091 for make_material_request, at line 1455 for make_sales_invoice. All of them enforce docstatus=1. All of them can still be reached from a picker that offered a draft, because the two layers don't know about each other.

The mismatch, in one sentence

The picker is populated per-caller in JS; the validator is populated per-mapper in Python. When a caller omits docstatus: 1 from the picker's filter, the validator still holds — but only after the user commits — and the resulting error looks phantom.

The fix — a client-side gate on the target form

You could hunt down every JS caller and add docstatus: 1 to its get_query_filters — for upstream files that means a PR against frappe/erpnext, for custom apps a scattered audit, and neither survives the next bench update. Don't. Do this instead: install a client script on each target DocType that patches erpnext.utils.map_current_doc once on refresh, injecting docstatus: 1 into every picker's filters.

// Custom Script → DocType: Purchase Invoice
// Pre-filters the "Get Items From → Purchase Receipt" picker to submitted docs only.
frappe.ui.form.on('Purchase Invoice', {
  refresh(frm) {
    if (frm.doc.docstatus !== 0) return;

    // Wait for erpnext.utils.map_current_doc to register buttons, then
    // override the picker's get_query so drafts never reach the UI list.
    const orig = erpnext.utils.map_current_doc;
    if (orig && !orig.__mithtech_patched) {
      erpnext.utils.map_current_doc = function (opts) {
        if (opts.source_doctype === 'Purchase Receipt') {
          opts.get_query_filters = Object.assign({}, opts.get_query_filters, {
            docstatus: 1,
            status: ["not in", ["Closed", "Completed", "Return Issued"]],
    is_return: 0
          });
        }
        return orig.call(this, opts);
      };
      erpnext.utils.map_current_doc.__mithtech_patched = true;
    }
  }
});

Fix guide, step by step

What if buying owns POs and accounts owns invoicing?

The above assumes one team owns both source and target creation. In many SMEs they don't — buying issues Purchase Orders, stores books Purchase Receipts, accounts books Purchase Invoices from those PRs. That split is the whole reason drafts leak in the first place.

The critical thing this split gets right: the client-script gate is a UX correction on the target form, not a permission override on the source. Stores keeps its scope; accounts stops filing phantom bug tickets against ERPNext.

Gates and automation — the permanent fix

The client-script snippet is the minimum. If you run a custom app already, package the same guard into it so it applies across sites without per-site Client Script maintenance.

// Custom Script → DocType: Purchase Invoice
// Patches ERPNext's shared map_current_doc so every source DocType's
// picker is pre-filtered to submitted docs.
frappe.ui.form.on('Purchase Invoice', {
  refresh(frm) {
    if (frm.doc.docstatus !== 0) return;
    const orig = erpnext.utils.map_current_doc;
    if (!orig || orig.__mithtech_patched) return;

    erpnext.utils.map_current_doc = function (opts) {
      opts.get_query_filters = Object.assign({}, opts.get_query_filters, {
        docstatus: 1,
      });
      return orig.call(this, opts);
    };
    erpnext.utils.map_current_doc.__mithtech_patched = true;
  }
});

What each recipe actually enforces

When is any of this actually material?

A concrete threshold you can lift into your SOP

If your accounts team is going to run this gate as part of routine site hygiene, they need a written policy on which target DocTypes get the client script by default:

Mapper Gate Policy (draft — for engineering-lead review): Install the docstatus: 1 picker gate on any target DocType whose Get Items From button pulls from a source DocType that supports drafts (docstatus 0). Default coverage: Purchase Invoice, Purchase Order, Purchase Receipt, Delivery Note, Sales Invoice, Sales Order. Optional coverage: Quotation, Supplier Quotation, Material Request. The server-side before_insert reject-drafts guard is mandatory on the same list if any custom app or external integration calls the mapper directly via REST or frappe.call. Review quarterly; retire the gate on a target DocType only after a documented decision that mapping from drafts is a legitimate business flow.

Two things to notice about writing this down rather than leaving it to ad-hoc fixes:

• The gate is cheap to install and cheap to remove. There's no reason to leave a target DocType exposed unless there's an explicit business case.
• A written list survives staff churn. The next accounts hire who hits the picker in a fresh state won't wonder whether it's meant to show drafts — they'll check the SOP.

Related issues you may also hit

• ERPNext Landed Cost & FX Gone Wrong — the Get Items From → Purchase Receipt flow is the same pattern; if the picker offers a draft PR the FX gate is defeated too.
• ERPNext Landed Cost Voucher primer — LCVs are also created via frappe.model.mapper from Purchase Receipts; the same docstatus mismatch shows up in the LCV picker.
• ERPNext approval workflow setup — if you need docstatus-plus-workflow-state gating on the source form, the two mechanisms combine cleanly.
• ERPNext bugs, real fixes from GitHub and the forum — general index of picker/mapper mismatches we track.

FAQ

Closing

The "Get Items From" picker isn't buggy; it's under-specified. The picker is populated per-caller in JavaScript, the mapper is validated per-mapper in Python, and when the two disagree the resulting error message reads like an ERPNext bug even though both layers are behaving exactly as coded. Install the client-script gate on your target DocTypes, keep the server-side validator intact, and the entire class of ticket disappears.