KSEF-21401:Document does not conform to the KSeF XSD schema
Fix: Regenerate the invoice against the exact FA schema version declared in the session header, fix each schema violation using the exceptionDetailList (missing required elements, wrong data types, wrong element order, unknown namespaces), and resubmit. Provide the required value in the free validator.
KSeF error 21401 ("Dokument nie jest zgodny ze schemą (xsd)") is returned when the invoice payload fails XSD schema validation against the FA schema published by the Polish Ministry of Finance. The API rejects the payload before any business validation runs, so no reference number is issued and the invoice is not stored.
Engine Classification
Business data required · Explicit input workflow · No assumptions made
What is KSEF-21401?
KSEF-21401 is a fatal validation rule defined in the ksef specification (POL national rules). It validates the Send and asynchronously on batch endpoints. When it fails, the API returns HTTP 400 with exceptionCode 21401 and, when available, an exceptionDetailList of XPath locations and XSD messages. element under online > Invoice in the UBL invoice XML.
When this rule fires, the invoice is rejected by Peppol access points and never reaches the buyer.
Target path: The KSeF ingestion pipeline validates every submission against the currently active FA schema (FA(2) or FA(3) for KSeF 2.0). Validation happens synchronously on /online/Invoice/Send and asynchronously on batch endpoints. When it fails, the API returns HTTP 400 with exceptionCode 21401 and, when available, an exceptionDetailList of XPath locations and XSD messages.
Why This Error Matters
21401 is the single most common error KSeF developers see during integration. Every unrecognised element, out-of-order child, or wrong-format decimal triggers it. Because the invoice is never stored, there is no audit trail and no reference number — from the ERP's perspective, the submission simply disappeared. Repeated 21401s during a rollout can look like a KSeF outage when the fault is entirely in the payload.
KSEF-21401 is a hard failure — the invoice must be corrected and re-sent before it can reach the recipient.
Blocks invoicing entirely — no KSeF number, no legal proof of issue. In the mandatory-KSeF regime effective 2026, this means the invoice cannot be delivered to the buyer and cannot be booked for VAT purposes.
Validator Behavior
- ·Causes invoice rejection
- ·Error returned: KSEF-21401
- ·Specification: ksef
How to Fix It
XML Example
Generic example based on the rule's target XPath. Your actual XML structure may differ.
<!-- Triggers validation error --> <Send and asynchronously on batch endpoints. When it fails, the API returns HTTP 400 with exceptionCode 21401 and, when available, an exceptionDetailList of XPath locations and XSD messages.></Send and asynchronously on batch endpoints. When it fails, the API returns HTTP 400 with exceptionCode 21401 and, when available, an exceptionDetailList of XPath locations and XSD messages.>
<!-- Corrected --> <Send and asynchronously on batch endpoints. When it fails, the API returns HTTP 400 with exceptionCode 21401 and, when available, an exceptionDetailList of XPath locations and XSD messages.>VALID_VALUE</Send and asynchronously on batch endpoints. When it fails, the API returns HTTP 400 with exceptionCode 21401 and, when available, an exceptionDetailList of XPath locations and XSD messages.>
Technical Reference
The KSeF ingestion pipeline validates every submission against the currently active FA schema (FA(2) or FA(3) for KSeF 2.0). Validation happens synchronously on /online/Invoice/Send and asynchronously on batch endpoints. When it fails, the API returns HTTP 400 with exceptionCode 21401 and, when available, an exceptionDetailList of XPath locations and XSD messages.Code Example
// Validate locally against FA(3) before submission
import { XMLValidator } from 'fast-xml-parser';
import { validateXML } from 'xmllint-wasm';
const result = await validateXML({
xml: [{ fileName: 'invoice.xml', contents: invoiceXml }],
schema: [faSchemaXsd]
});
if (result.errors.length) {
throw new Error(`XSD errors: ${JSON.stringify(result.errors)}`);
}Common Causes
- ·FA schema version mismatch — submitting FA(2) to a KSeF 2.0 endpoint after the November 2025 upgrade.
- ·Element ordering wrong — FA uses strict xs:sequence and children must appear in the declared order.
- ·Decimal precision — amounts serialized with more decimals than xs:decimal(19,2) allows.
- ·Date/time format — dates using DD.MM.YYYY or YYYY/MM/DD instead of ISO 8601 YYYY-MM-DD.
- ·Unknown or misspelled element (e.g., <P_1A> vs <P1A>) that the schema does not declare.
- ·Missing required child in a group (BR-* level omissions still surface as schema violations when the field is xs:minOccurs=1).
- ·Wrong namespace prefix or missing tns:xmlns declaration.
Seeing this in production? The API handles KSEF-21401 automatically. See the fix response →
Commonly Seen In
Frequently Asked Questions
Yes. 21401 is returned before the invoice enters the system, so it has no KSeF reference number and no legal effect. You do not need a correction invoice — fix the XML and resubmit as a fresh document.
Partially. Structural issues (element order, namespace, decimal formatting, whitespace) are auto-fixed. Missing required business data (invoice number, amounts, buyer NIP) requires input from your ERP because the fields are not present at all.
The Ministry of Finance updates the FA schema on scheduled effective dates. If your submission crosses the switchover, the same XML that validated yesterday against FA(2) can fail today against FA(3). Check the currently active schema URI on the /online/Session endpoint.
The Ministry of Finance publishes FA schemas at gov.pl/web/kas under Struktury dokumentów XML. Always validate locally against the exact XSD before sending — do not use KSeF as your development validator, or you will consume your rate-limit quota on schema errors.
During any FA schema transition (FA(2) → FA(3), and future 2026 hotfixes), any ERP with a manual mapping layer — SAP DRC, Comarch, custom Odoo — sees a spike. Vendors with centrally-maintained connectors (Symfonia SaaS, Fakturownia) get the schema update automatically.
Related Errors
Related Content
Last updated: 28 July 2026
Validate your invoice
Drop your XML here to check for KSEF-21401
Fix KSEF-21401 with guided input
Upload your invoice and we'll ask for the missing data, then apply a safe, auditable fix.