GST portal error codes — what they mean and how to fix them
A GST portal error code is not an obstacle — it is a diagnosis. Each code tells you precisely which validation failed, and almost all of them are fixed in the source data rather than on the portal. This guide decodes the codes filers actually meet: the RET191… series thrown by the GSTR-1 offline utility, the numeric codes returned by the e-invoice portal, and the emSigner connection failure that stops a return being signed.
Every code listed here is reproduced from the source named against it. Error text on the portal is occasionally reworded between releases, so treat the message as indicative and the code as authoritative.
How GST error codes are structured
Two different systems produce two different formats, and knowing which you are looking at halves the diagnosis:
- RET191nnn — returned by the GST return-filing system, typically when a JSON file generated by the offline utility or accounting software is uploaded. “RET” identifies the returns module; the number identifies the failed validation.
- Four-digit numeric codes (2150, 3028…) — returned by the Invoice Registration Portal when an e-invoice payload is rejected.
- No code at all — browser, session or signing failures, including the emSigner error. These are local to your machine, not to your data.
GSTR-1 and offline utility errors (RET191 series)
These appear after a JSON upload, usually in the error report you download from the portal rather than on screen. The fix is almost always to correct the invoice in your books and regenerate the JSON — editing the JSON by hand creates fresh structural errors.
| Code | What it means | How to fix it |
|---|---|---|
| RET191106 | Error in JSON structure validation — the portal cannot parse the file. | Confirm the GSTIN is present in the file and regenerate the JSON using the current version of the offline utility. An outdated utility is the usual cause. |
| RET191113 | The GSTIN is invalid. | The GSTIN in the JSON does not match the account you are uploading to. Check you are logged into the right GSTIN, and verify the counterparty GSTIN. |
| RET191114 | Invoice date is before the date of registration. | You cannot report a tax invoice dated earlier than your GST registration. Correct the invoice date, or report the supply through the correct period. |
| RET191115 | Invoice number does not exist / is not valid. | GST invoice numbers must be 16 characters or fewer and follow a consistent series. Remove special characters and re-upload. |
| RET191124 | Original invoice is invalid. | Raised on credit and debit notes where the original invoice number or date does not match a reported invoice. Verify the reference against the original entry. |
| RET191133 | Invoice already exists with the same or a different counterparty GSTIN. | A duplicate. Delete the existing entry on the portal before re-uploading the corrected one — uploading again without deleting repeats the error. |
| RET191175 | The rate entered is not valid as per the rate list. | Only notified slabs are accepted. Check the rate against the current schedule for that HSN before regenerating. |
| RET191179 | Place of supply and supplier state must differ for an inter-state supply. | You have charged IGST on a transaction the portal reads as intra-state, or vice versa. Correct the place of supply, then the tax heads follow. |
| RET191205 | Tax amount is not in line with taxable value and rate. | A rounding or computation mismatch. Round the taxable value to two decimals and let the software recompute tax rather than typing it manually. |
Two of these — RET191175 and RET191179 — are worth pausing on. They are usually flagged as technical errors, but they point at a substantive mistake in how the supply was treated. Correcting the JSON without correcting the underlying invoice leaves the books and the return saying different things.
e-Invoice (IRP) error codes
These are returned when an invoice payload is rejected by the Invoice Registration Portal. The codes and resolutions below follow the National Informatics Centre’s own note on the most frequent errors.
| Code | What it means | How to fix it |
|---|---|---|
| 2150 | Duplicate IRN. An IRN already exists for that combination of supplier GSTIN, document type, document number and financial year. | Usually a retry after a timed-out request, not a genuine duplicate. Resubmit the identical payload to retrieve the IRN already generated, and flag the document in your system once an IRN is received so it is never sent twice. NIC advises limiting retries to two. |
| 3028 / 3029 | GSTIN is inactive, does not exist, or has not synchronised to the IRP. | Check the GSTIN’s status on the document date using Search > Taxpayer on the e-invoice portal. If it is active on the GST portal but not on the IRP, use “Update from GST Common Portal” to force a sync. |
| PIN code mismatch | The PIN code supplied does not belong to the state supplied. | Download the state-wise PIN master from the portal’s Master Codes and validate the pairing inside your billing software, not at submission time. |
| Invalid HSN | The HSN does not exist in the master, or is wrongly formatted. | Take the HSN from the portal’s Master Codes. Do not pad with leading zeros or append suffixes — the value must match the master exactly. |
The emSigner error — “Failed to establish connection to the server”
This one is not a data problem, which is why it resists every attempt to fix it in the return. emSigner listens on a local port and the browser talks to it over https://127.0.0.1. Older builds used port 1645; current builds use 1585. When the browser is still trying the old port, the signing request never reaches the utility.
The clean fix:
- Uninstall emSigner and your DSC token driver completely.
- Update the browser, then allow
https://127.0.0.1:1585in the browser’s JavaScript exceptions. - Download the current emSigner from Register/Update DSC on the GST portal.
- Right-click and Run as administrator — emSigner cannot bind the port otherwise.
- Reinstall the token driver, insert the DSC, restart the machine.
- Open
https://127.0.0.1:1585once in the browser and accept the local certificate warning. Until this is done the connection is refused silently.
Step 6 is the one most often missed. The local certificate is self-signed, and the browser will not talk to emSigner until you have accepted it manually at least once.
Errors with no code at all
“System error”, “Something went wrong” and silent session drops carry no code and need a different approach. Work through them in this order before assuming a portal outage:
- Clear the session. Log out, clear cache and cookies for the portal, close every tab and log in again. Stale session tokens produce errors that look like data failures.
- Use one tab. Two GST portal tabs on the same login will invalidate each other’s session mid-submission.
- Check the size of what you are uploading. Very large JSON files time out rather than failing cleanly. Split by section and upload in parts.
- Try outside peak hours. Genuine portal congestion clusters in the last three days before a due date, which is also when it costs you most.
If a return genuinely cannot be filed because of a portal failure, record it — dated screenshots including the error and the timestamp. That record is what supports a request for waiver of late fee, and it cannot be reconstructed afterwards.
When an error code is a compliance problem in disguise
Some codes are worth treating as findings rather than obstacles. A recurring RET191179 means place of supply is being determined wrongly somewhere in the billing process, and every affected invoice has charged the wrong tax. Repeated RET191133 duplicates suggest the invoice series is being reused. Persistent 2150 responses point at a retry loop in the billing integration that will eventually produce genuinely duplicated documents.
Each of these will surface later as a mismatch between GSTR-1, GSTR-3B and the counterparty’s GSTR-2B — which is where notices begin. If a code keeps returning, fix the process, not just the file.
Frequently asked questions
Can I edit the JSON file directly to clear an error?
It is possible and almost always a mistake. Hand-edited JSON commonly fails structure validation (RET191106) on the next upload, and it leaves your books and your return disagreeing. Correct the entry in the accounting system and regenerate.
Why does an invoice show as a duplicate when I have not uploaded it?
Either it was uploaded in an earlier session that appeared to fail, or the same invoice number has been reused in the same financial year. Check the saved records on the portal before re-uploading.
Does an error code mean my return is late?
A return is late only if it is not filed by the due date. An error caught with time in hand costs nothing. This is the practical argument for filing well before the deadline rather than on it.
The GSTIN is active on the GST portal but the IRP says it is inactive.
The two systems synchronise on a delay. Use “Update from GST Common Portal” on the e-invoice portal to force a refresh before treating it as a registration problem.
Where to go next
- GST portal dashboard and login guide — if the problem is getting in rather than filing.
- e-Invoice portal, registration and IRN guide — the process behind the IRP codes above.
- Replying to a GST notice in DRC-01 or ASMT-10 — where unresolved mismatches end up.
- DRC-03 voluntary payment — correcting a short payment before it is demanded.
- TDS return filing error codes — the equivalent reference for TDS.
Getting this filed without the guesswork
Most of these errors take minutes to fix once identified and hours to fix by trial and error against a deadline. TAXAJ files GST returns for businesses across India and deals with these codes as routine work rather than as emergencies.
- GST return filing — monthly and quarterly filing, handled end to end.
- e-Invoicing under GST — setup and IRN generation.
- GST registration — new registrations and amendments.
Schedule a call with our GST team, or track an existing engagement in the TAXAJ client portal.
