GSTR-1 JSON errors happen when the file you generate does not match the validation rules the GST portal applies on upload, most often because of an invalid GSTIN checksum, a duplicate invoice number, an invalid date or return period, a tax rate mismatch, or a missing mandatory field. Each of these shows up as a rejected or partially processed upload with an error against specific rows, and each has a specific, fixable cause. This guide groups the common categories of GSTR-1 JSON validation failures and explains how to resolve each one.
Because the GST portal's exact error text and codes are updated periodically, this guide describes error categories you are likely to encounter rather than quoting specific portal error codes verbatim. Always cross-check the exact message shown against the current portal guidance at www.gst.gov.in.
What Is the GSTR-1 JSON File?
The GSTR-1 JSON file is the structured data file the GST portal expects when you upload your outward supply return offline instead of entering every invoice manually online. It contains your B2B invoices, B2C summaries, credit and debit notes, HSN summary, and document summary in a fixed format that the portal's offline utility or API validates before accepting.
Most sellers and accountants generate this JSON from accounting or GST software, such as an export from GSTR-1 automation in OneBooks GST, rather than typing invoices into the portal one at a time.
Why Does the GST Portal Reject a GSTR-1 JSON File?
The portal validates every row of the JSON against a set of rules before it accepts the return: GSTIN format and checksum, invoice number uniqueness within the financial year, valid dates within the return period, correct tax rate and amount combinations, and presence of every mandatory field for the invoice type. If a single invoice fails a rule, the portal typically processes the rest of the file and reports the failing rows separately, rather than rejecting the entire file outright, though behaviour can vary by upload method.
Common GSTR-1 JSON Error Categories and How to Fix Them
| Error Category | Typical Cause | How to Fix It |
|---|---|---|
| Invalid GSTIN checksum | A digit was mistyped, or the GSTIN was copied with a formatting issue | Re-verify the GSTIN against the buyer's registration certificate or the GST portal's search tool and correct the exact string |
| Duplicate invoice number | The same invoice number was used twice in the same financial year, sometimes across different series | Check your invoice numbering series for accidental repeats, especially when merging data from multiple sales channels |
| Invalid date or return period | An invoice date falls outside the return period being filed, or is in an unrecognised date format | Confirm the invoice date belongs to the period you are filing and that dates are in the format the portal expects |
| Tax rate mismatch | The tax rate applied does not match a valid GST rate, or the tax amount does not match taxable value times rate | Recalculate the tax amount from the taxable value and the applicable rate, and confirm the HSN-linked rate is current |
| Missing mandatory field | A required field for that invoice type, such as place of supply or buyer GSTIN for a B2B invoice, was left blank | Check the invoice type's required fields and fill every mandatory field before regenerating the JSON |
How Do You Fix an Invalid GSTIN Checksum Error?
A GSTIN checksum error means the 15-character GSTIN string does not pass the portal's internal validation, usually because of a transposed digit or an extra character copied in from a spreadsheet. Re-type the GSTIN directly from the buyer's registration document rather than copy-pasting from a source that may have trailing spaces or hidden characters, and confirm the state code prefix matches the buyer's registered state.
How Do You Fix a Duplicate Invoice Number Error?
This error appears when two invoices in the same financial year share an identical invoice number, which the portal treats as an integrity issue. It is common when a business runs separate invoice series for different sales channels, such as marketplace orders and direct sales, and the series overlap. Review your numbering convention and, where needed, add a channel-specific prefix so no two invoices in a financial year can collide.
What Causes Invalid Date or Return Period Errors?
These occur when an invoice date does not fall inside the return period selected, or when a note or amendment is dated inconsistently with the original invoice it references. Confirm you are filing the correct month or quarter, and that every invoice date genuinely belongs to that period before you export the JSON. This is also worth checking against your GSTR-1 document summary, which lists the invoice number ranges you are declaring for the period.
How Do You Avoid Tax Rate Mismatch Errors?
A tax rate mismatch typically means the tax amount on an invoice line does not equal taxable value multiplied by the stated rate, or the rate itself is not a valid GST slab. This can happen after a manual correction to one field without recalculating the other. Recompute tax amounts from taxable value rather than editing tax and value independently, and confirm HSN codes map to the rate you expect using the GST calculator.
What Mandatory Fields Does GSTR-1 Require?
Mandatory fields vary by invoice type, but commonly include invoice number and date, buyer GSTIN for B2B invoices, place of supply, HSN or SAC code, taxable value, applicable tax rate, and tax amount split by IGST, CGST, and SGST as relevant. A GST-compliant invoice generated with all required fields at the point of sale is far less likely to produce a missing-field error later; see our guide on GST invoice format and mandatory fields for the full list.
How Can You Prevent JSON Errors Before Upload?
- Run a pre-filing validation pass on GSTIN, invoice numbers, dates, and rates before generating the JSON.
- Cross-check the GSTR-1 document summary for gaps or unexpected duplicate ranges in invoice numbering.
- Reconcile the return against your books before export, not after a rejected upload.
- Keep a single, consistent GSTIN and rate reference so HSN-to-rate mapping does not drift between invoices.
OneBooks GST is a GST and accounting platform for Indian businesses that prepares GSTR-1, including B2B, B2C, credit and debit notes, and HSN summary, and surfaces validation warnings on the data before you export the GSTR-1 JSON, CSV, Excel, Tally XML, Miracle, or Profit NX file. Reviewing these warnings inside GSTR-1 automation before export catches many of the categories above without waiting for a portal rejection. If a return still comes back with an error you cannot place, OneBooks GST support can help you interpret it.
Frequently Asked Questions
Why does my GSTR-1 JSON file fail on the GST portal?
A GSTR-1 JSON file most commonly fails because of an invalid GSTIN checksum, a duplicate invoice number within the financial year, a date outside the return period, a tax rate that does not match the taxable value, or a missing mandatory field for that invoice type.
Does one invoice error reject the entire GSTR-1 JSON file?
Usually the portal processes the valid rows and reports only the failing invoices as errors, though this can depend on the upload method and file structure, so always check the full error summary rather than assuming a single failure blocks everything.
How do I check if a GSTIN is valid before filing?
You can verify a GSTIN's format and registration status using the search tool on the official GST portal at www.gst.gov.in before including it in your GSTR-1 data.
What is the most common cause of duplicate invoice number errors?
Duplicate invoice number errors are most common when a business uses overlapping numbering series across different sales channels, such as marketplace orders and direct invoicing, without a distinguishing prefix.
Can GST software prevent JSON errors before I upload to the portal?
Yes, GST software that runs validation checks on GSTIN format, invoice numbering, dates, and tax rate consistency before generating the JSON can catch most of these issues ahead of the portal upload, reducing rejected filings.
