Why Is My Convert JSON File to CSV Still Breaking on Nested Data?

You drop a .json file into a converter, hit the button, and the CSV comes out looking like a ransom note — [object Object] in half the cells, columns that don't line up, or a single row where you expected two hundred. The file converted, technically. It just didn't convert usefully. That's the most common complaint I hear about trying to convert a JSON file to CSV, and it almost always traces back to the same handful of causes.

The real reason nested JSON breaks CSV

CSV is a flat grid: rows and columns, one value per cell. JSON doesn't care about grids. It happily nests objects inside objects and arrays inside arrays, sometimes ten levels deep. When a converter hits a nested object and doesn't know what to do with it, it has two lazy options: stringify the whole thing into one ugly cell, or drop it entirely.

A typical API response looks like this:

{
  "order_id": 4471,
  "customer": {
    "name": "Dana Ruiz",
    "address": { "city": "Austin", "zip": "78701" }
  },
  "items": [
    { "sku": "A-12", "qty": 2 },
    { "sku": "B-07", "qty": 1 }
  ]
}

Flattened properly, that becomes columns like customer.name, customer.address.city, and items.0.sku. Flattened badly, it becomes customer = [object Object] and items = [object Object],[object Object]. Same input, wildly different output.

Diagnose before you convert

Before blaming the tool, check three things in your source file:

1. Is the root an array or a single object? A top-level array of records converts cleanly. A single object converts to one row unless you wrap it in [ ] first.
2. How deep does the nesting actually go? Count the braces. If you're past ten levels, some free converters will truncate rather than flatten.
3. Are there arrays of objects? These are the ones that produce the most columns, because each unique key inside the array becomes its own column.

A quick way to spot the problem: open the JSON in a text editor and search for "{" — every match is a nested object that needs a flattening strategy.

The fix: flatten in the browser, then export

The JSON ↔ CSV Converter handles this without you writing a script. It runs PapaParse and SheetJS locally in your browser, so the file never gets uploaded anywhere. Here's the workflow that works:

1. Paste or drop your file. Free tier accepts files up to 25MB. If you're over that, the Pro tier goes to 50MB with a progress indicator.
2. Choose JSON→CSV. The converter flattens nested objects up to 10 levels deep on the free tier. If your payload is deeper than that, Pro unlocks deeper flattening.
3. Check the header row. You should see dotted paths like customer.address.city, not [object Object]. If you see the latter, your nesting exceeded the flatten depth.
4. Download or copy. The result is a real CSV you can open in Excel, Google Sheets, or Numbers.

If you need Excel specifically, the same tool exports .xlsx directly — useful when a client wants a workbook, not a comma-separated file.

When arrays of objects blow up your column count

An array of two items with five keys each adds ten columns. An array of fifty items adds two hundred and fifty. This is where conversions that "worked" produce a spreadsheet nobody can read.

Two practical options:

• Flatten anyway if the array is short and consistent. Dotted paths like items.0.sku and items.1.sku are ugly but usable for a one-off report.
• Split the file if the array is long. Convert the parent object to one CSV and the array to a second CSV, then join them in your spreadsheet tool by a shared key like order_id.

There's no universal right answer here — it depends on whether the person receiving the CSV needs a single flat table or is comfortable with two related files.

Prevention: clean the JSON before it reaches the converter

Most conversion pain is really source-data pain. A few habits save time:

• Ask the API for flat output. Some endpoints support a ?format=flat or similar parameter. If yours does, use it.
• Normalize arrays to fixed length. If items always has exactly three entries, the flattened output is predictable. If it varies from one to fifty, it isn't.
• Validate first. Paste the JSON into a linter or your editor's JSON validator before converting. A single trailing comma will fail the whole parse and you'll blame the converter.
• Keep a copy of the original. Once flattened, you can't easily un-flatten. Keep the .json around in case you need a different column layout later.

What this tool won't do

It converts JSON↔CSV and exports .xlsx, all client-side. It does not connect to your database, pull from a data warehouse, or schedule recurring exports. If you need those, you're looking at a different class of software. For the everyday job — an API response, an export from a headless CMS, a log dump — a browser converter is faster than spinning up a Python script, and it doesn't require you to trust a server with the file.

If privacy is the reason you're avoiding cloud converters, the privacy page spells out exactly what stays local. Short version: the conversion happens in your tab, and nothing is stored on Toolkite's servers. The one exception is the optional Pro feature that fetches a JSON file from an API URL, which necessarily routes through a CORS proxy — everything else is local.

For batch work, Pro handles up to ten files at once, which beats converting them one by one. And if you're generating test data to convert in the first place, the mock data tool pairs well with this workflow.

FAQ

Why does my CSV show [object Object] instead of the actual values?

That happens when the converter hits a nested object and doesn't flatten it — it just stringifies the object into a single cell. You need a converter that expands nested keys into dotted column headers like customer.address.city. The JSON ↔ CSV Converter does this up to 10 levels deep on the free tier.

How deep can nested JSON go before flattening fails?

On the free tier, the converter flattens up to 10 levels. If your JSON is deeper than that, the innermost objects will come through as stringified text rather than separate columns. The Pro tier unlocks deeper flattening for payloads that go beyond that limit.

What's the maximum file size I can convert for free?

Free conversions accept files up to 25MB. If you regularly work with larger exports, the Pro tier raises that to 50MB and adds a progress indicator so you can see how far along the conversion is.

Can I convert a JSON file to Excel instead of CSV?

Yes. The same tool exports .xlsx directly, which is useful when the person receiving the file wants a workbook rather than a comma-separated file. The conversion still happens entirely in your browser.

Does the converter upload my JSON file to a server?

No. The conversion runs locally in your browser using PapaParse and SheetJS, so the file never leaves your device. The only exception is the optional Pro feature that fetches JSON from an API URL, which routes through a CORS proxy.

Why did my JSON fail to parse entirely?

Usually a syntax error — a trailing comma, a missing quote, or an unescaped character. Validate the JSON in your editor before converting. A single malformed character will cause the whole parse to fail, and it's rarely the converter's fault.