Offline utility JSON upload error

It is 11:05 pm. The GSTR-1 due window is close. You prepared invoices in the Returns Offline Tool, clicked generate JSON, and uploaded the file on gst.gov.in. The portal threw a red error. The JSON sits on the desktop with a name you barely recognise. The error log opened in a notepad you closed by habit. The billing software vendor is asleep. The helper has gone home. You still need this month’s B2B rows on the portal.

The offline tool is a helper, not a second GST department. The return is filed only after a successful upload and the usual file step on the Returns Dashboard. A JSON on your computer is not GSTR-1.

What the offline tool is for

Many small shops type invoices in an Excel-like offline utility that GSTN publishes. You download it from the official site, not from a random “GST tool 2024.zip” on a blog.

Usual download area:

gst.gov.in → Downloads → Offline Tools → Returns Offline Tool

(Use the name shown on the live Downloads page. GSTN renames builds.)

You install the version that matches the return you are filing. An old 2022 installer will fight a 2026 JSON schema. Before you type fifty invoices, open Help or the start screen of the tool and read the version. If the portal upload page says your JSON is from an unsupported version, stop typing and fetch the new official installer.

The tool lets you enter B2B, B2C, credit notes, and other GSTR-1 tables without staying logged in. Then it creates a JSON. That JSON is what you upload.

The upload path on the portal

Log in only on https://www.gst.gov.in.

gst.gov.in → Services → Returns → Returns Dashboard

Open GSTR-1 for the correct period. Choose the prepare offline / upload JSON option the dashboard shows (wording is along the lines of Prepare Offline). Select the JSON file. Wait. Do not close the tab.

If the portal accepts the file, you still must review the invoices on the online GSTR-1 and file with OTP or DSC. Upload is not file.

If the portal rejects the file, it usually offers an error file or error log. Download it. That log is more useful than staring at the JSON in Notepad.

How to read the error log without panic

Open the error file in Excel if it is CSV, or in the tool’s error screen if it opens there. Look for a row number, a GSTIN, an invoice number, and a short reason.

Typical reasons shops actually see:

• Buyer GSTIN length or checksum wrong
• Invoice number with a space, slash, or Hindi character the schema hates
• Duplicate invoice number in the same year
• Tax amount not matching rate times taxable value, off by a rupee
• Place of supply blank or a state code that does not match IGST versus CGST-SGST
• Credit note pointing at an invoice that is missing
• HSN missing where the table now requires it
• Date outside the period you selected on the dashboard

Fix the row in the offline tool (or in your billing export), generate a fresh JSON, upload again. Do not edit the JSON by hand unless you truly know the schema. One missing comma and the whole file dies.

If the log says “file is empty” or “no records”, you generated JSON from the wrong return type or you never imported the sheet. Open the tool, confirm the GSTIN in the header matches the login, confirm the period, and count the invoice rows on the B2B sheet. Zero rows will upload nothing useful.

Invoice rows: the shop-floor checks that prevent the error

Before generate JSON, walk the B2B sheet like a physical bill book.

GSTIN of buyer: copy from the buyer’s certificate or from Search Taxpayer on gst.gov.in, not from an old visiting card.

Invoice number: same series you print on paper. Do not restart numbering every Monday if your printed bills do not.

Taxable value and tax: if the paper bill says 18 percent, the row must say 18 percent. Do not round tax in the sheet one way and on paper another way.

Document type: invoice versus credit note versus debit note. Mixing them is a classic error-log filler.

If you import from billing software, map columns once and save the mapping. A software update can shift a column silently. Spot-check five invoices against paper every filing, not only when the portal shouts.

Version of the tool, Windows, and “it worked last month”

GSTN updates the offline utility when GSTR-1 tables change. Last month’s shortcut on the desktop can be stale. When an upload error mentions version, schema, or “invalid file”, download the current official tool again. Uninstall the old one if the installer asks. Do not keep two tools with similar icons and guess.

If the tool will not open, check that you are not running a blocked download from a copy site. Official file, official checksum if GSTN publishes one. Antivirus can quarantine JSON generation; if the generate button does nothing, look in the tool’s log folder.

Large files time out. If you have thousands of B2C rows, split the way the official manual allows, or use the online entry for the leftover chunk. Do not sit on a 2G dongle at midnight with a 20 MB JSON and call the portal broken. Try a stable connection. Retry once. If the error is a validation error, a faster dongle will not fix a bad GSTIN.

After a successful upload, still look at the online tables

Open GSTR-1 online. See whether B2B count matches your bill book. If the JSON uploaded an old month’s file, you will see last month’s invoices again or a duplicate error. Always check the period in the JSON filename and in the tool header.

File GSTR-1 from the dashboard. Then, when 3B is due, the outward tax should talk to 3B. Mismatch between GSTR-1 and GSTR-3B is how notices start. The offline tool does not file 3B. 3B is a separate tile:

gst.gov.in → Services → Returns → Returns Dashboard → GSTR-3B

If JSON upload fails and time is short, you may enter invoices online directly for a small count. That is legal. Do not skip GSTR-1 because the JSON failed. Do not issue invoices that never appear in GSTR-1. Do not create a second set of bills “only for the portal”.

When to stop and get a person next to the computer

If the error log points at hundreds of GSTIN checksum failures, your import file is the patient, not the portal. If Aadhaar or DSC is failing, that is a signing problem, not a JSON problem. If the dashboard will not open GSTR-1 because a previous return is pending, file the pending one first. The offline tool cannot jump the queue.

Keep the error log. A local helper can read it faster than a vague “the upload is failing” on the phone.

FAQ

Does generating JSON mean GSTR-1 is filed?

No. JSON is only a file. You must upload it on gst.gov.in from Returns Dashboard → GSTR-1 → prepare offline, then review and file with OTP or DSC. Until status is filed, GSTR-1 is not done.

The error log names invoice rows. Should I delete the whole JSON and start from zero?

Usually no. Fix the named rows in the offline tool, generate a new JSON, and upload again. Start from zero only if the GSTIN in the header is wrong or you used the wrong period.

Which offline tool version should I use?

The current official Returns Offline Tool from gst.gov.in Downloads. If the portal rejects the schema, update the tool. Do not use a copied zip from a chat group.

Can I upload JSON and skip checking B2B on the website?

You can, and you will regret it. After upload, open GSTR-1 online and match invoice count and tax with your bill book. Then file. Wrong rows that got through validation still become your return.

GST Atka is not a GSTN office. File on gst.gov.in. Rules change. Do not evade tax. Personal case: get local help.