JSONToTable

TOON Error Handling & Troubleshooting

Complete guide to identifying, understanding, and fixing TOON format errors

Published: January 2025 • 11 min read

Look, TOON format is pretty straightforward, but errors happen—especially when you're converting from JSON or editing manually. We've all been there: your validator throws an error, and you're left wondering what "field count mismatch" actually means.

This guide walks through every common TOON error you're likely to hit, what causes it, and how to fix it fast. Pro tip: use our TOON Validator to catch these issues before they break your production code.

Common Error Categories

TOON errors fall into five main categories:

1. Length Marker Errors

Array length doesn't match declared count

2. Field Count Mismatches

Data row has wrong number of values

3. Syntax Errors

Invalid characters, quotes, or formatting

4. Indentation Issues

Inconsistent or incorrect indentation

5. Data Type Errors

Invalid boolean, null, or number formats

Error 1: Length Marker Mismatch

Error Message:

"Array length mismatch: expected 5 elements but found 3"

❌ Incorrect (causes error)

# Declared [5] but only 3 items provided
customers[5]{id,name,email}:
  1,Sarah Mitchell,[email protected]
  2,Michael Chen,[email protected]
  3,Jennifer Kumar,[email protected]

Problem: Length marker says 5, but only 3 rows exist

✅ Correct (solution)

# Corrected to [3] to match actual count
customers[3]{id,name,email}:
  1,Sarah Mitchell,[email protected]
  2,Michael Chen,[email protected]
  3,Jennifer Kumar,[email protected]

Solution: Update length marker to match actual element count

Prevention:

Error 2: Field Count Mismatch

Error Message:

"Field count mismatch on row 2: expected 4 values but found 3"

❌ Incorrect (causes error)

# Field definition has 4 fields, but row 2 has only 3 values
products[3]{id,name,price,stock}:
  1,Laptop,999.99,15
  2,Mouse,29.99              # Missing stock value!
  3,Keyboard,79.99,8

Problem: Row 2 is missing the stock value (should have 4 values)

✅ Correct (solution)

# All rows have 4 values matching field definition
products[3]{id,name,price,stock}:
  1,Laptop,999.99,15
  2,Mouse,29.99,0            # Added missing value (0 for out of stock)
  3,Keyboard,79.99,8

Solution: Ensure each row has exactly as many values as defined fields

Common Causes:

  • • Missing trailing value (forgot last field)
  • • Extra comma creating empty value
  • • Value contains unescaped delimiter (comma in data)
  • • Copy-paste error from spreadsheet

Error 3: Delimiter Character in Data

Error Message:

"Field count mismatch: data contains delimiter character"

❌ Incorrect (causes error)

# Address contains comma, breaking parsing
addresses[2]{street,city,zip}:
  123 Main St, Suite 100,Boston,02101      # Comma in address creates 4 values!
  456 Oak Ave,Seattle,98101

Problem: First row has comma in "Suite 100," creating 4 values instead of 3

✅ Solution 1: Use Alternative Delimiter

# Use pipe (|) delimiter instead of comma
addresses[2]{street,city,zip}|:
  123 Main St, Suite 100|Boston|02101      # Comma in address is fine now
  456 Oak Ave|Seattle|98101

Solution: Add pipe symbol after field definition to change delimiter

✅ Solution 2: Quote the Value

# Quote values containing delimiters
addresses[2]{street,city,zip}:
  "123 Main St, Suite 100",Boston,02101    # Quoted value preserves comma
  456 Oak Ave,Seattle,98101

Solution: Wrap problematic value in double quotes

Recommended Delimiters:

  • • Comma (,): Default, use for simple data
  • • Pipe (|): Use when data contains commas (addresses, descriptions)
  • • Tab (\t): Use for data with commas and pipes

Error 4: Indentation Errors

Error Message:

"Inconsistent indentation: expected 2 spaces but found 4"

❌ Incorrect (causes error)

# Mixed indentation - some 2 spaces, some 4 spaces
user:
  name: "Alex"
    email: "[email protected]"    # 4 spaces instead of 2
  address:
      city: "Boston"              # 6 spaces instead of 4
    zip: "02101"                  # 4 spaces (inconsistent)

Problem: Inconsistent indentation levels throughout the document

✅ Correct (solution)

# Consistent 2-space indentation throughout
user:
  name: "Alex"
  email: "[email protected]"      # 2 spaces
  address:
    city: "Boston"                # 4 spaces (2 levels)
    zip: "02101"                  # 4 spaces (2 levels)

Solution: Use consistent 2-space indentation per level

Quick Fixes:

  • • Use TOON Formatter to auto-fix indentation
  • • Configure your editor to show whitespace characters
  • • Never mix tabs and spaces - use spaces only
  • • Standard: 2 spaces per indentation level

Error 5: Boolean and Null Type Errors

Error Message:

"Invalid boolean value: must be 'true' or 'false' (lowercase)"

❌ Incorrect (causes error)

# Uppercase boolean values and NULL
users[3]{name,active,role}:
  Sarah,TRUE,admin           # Should be: true
  Michael,False,user         # Should be: false
  Jennifer,true,NULL         # Should be: null

Problem: Booleans and null must be lowercase

✅ Correct (solution)

# Lowercase true, false, null
users[3]{name,active,role}:
  Sarah,true,admin           # Correct
  Michael,false,user         # Correct
  Jennifer,true,null         # Correct

Solution: Use lowercase true, false, null

Type Format Rules:

  • • Boolean: Must be true or false (lowercase)
  • • Null: Must be null (lowercase)
  • • Numbers: No quotes, can include decimals and negatives
  • • Strings: Must be in double quotes if containing special characters

Error 6: Missing or Incorrect Quotes

❌ Incorrect (causes error)

# Missing quotes on strings with spaces or special chars
users[2]{name,email,status}:
  Sarah Mitchell,[email protected],active       # Space in name needs quotes
  Michael,[email protected],'pending'         # Single quotes not allowed

✅ Correct (solution)

# Proper double quotes on strings
users[2]{name,email,status}:
  "Sarah Mitchell",[email protected],active     # Quoted
  Michael,[email protected],"pending"         # Double quotes

When to Use Quotes:

  • • Strings containing spaces: "Sarah Mitchell"
  • • Strings with special characters: "Price: $99"
  • • Strings with delimiters: "123 Main St, Suite 100"
  • • Always use double quotes, never single quotes

Error 7: Trailing Commas or Delimiters

Error Message:

"Trailing delimiter found: rows should not end with delimiter"

❌ Incorrect (causes error)

# Trailing commas create extra empty field
products[3]{id,name,price}:
  1,Laptop,999.99,          # Trailing comma!
  2,Mouse,29.99,            # Trailing comma!
  3,Keyboard,79.99,         # Trailing comma!

Problem: Trailing commas make parser think there's an extra empty field

✅ Correct (solution)

# No trailing commas
products[3]{id,name,price}:
  1,Laptop,999.99           # No trailing comma
  2,Mouse,29.99             # No trailing comma
  3,Keyboard,79.99          # No trailing comma

Solution: Remove trailing delimiters from all rows

Error 8: Incorrectly Formatted Empty Arrays

❌ Incorrect (causes error)

# Wrong ways to represent empty array
tags[]:                    # Missing length
tags:                      # Not marked as array
tags[0]: []               # Don't use JSON brackets

✅ Correct (solution)

# Correct empty array notation
tags[0]:                   # Length 0, no colon content needed

# Or in context:
user:
  name: "John"
  tags[0]:                 # Empty array
  active: true

Solution: Use [0] length marker with colon, no data after colon

Debugging Strategy

Step 1: Use TOON Validator

Paste your TOON into our TOON Validator for detailed error messages with line numbers.

Step 2: Check Line Number

Error messages include line numbers. Navigate to that line and check for syntax issues, count mismatches, or formatting errors.

Step 3: Verify Counts

Count array elements and verify length markers. Count fields in definition and values in each row. They must match exactly.

Step 4: Check Indentation

Enable "show whitespace" in your editor. Look for mixed tabs/spaces or inconsistent indentation levels.

Step 5: Test Conversion

Convert to JSON with TOON to JSON, then back to TOON with JSON to TOON. Compare with your original to spot differences.

Error Prevention Checklist

Follow these practices to avoid errors:

  • ☐Use automated conversion instead of manual writing when possible
  • ☐Always validate with TOON Validator before sending to production
  • ☐Count array elements carefully and verify length markers
  • ☐Use consistent 2-space indentation throughout document
  • ☐Check for trailing commas or delimiters
  • ☐Use lowercase for true, false, null
  • ☐Quote strings with spaces or special characters
  • ☐Use pipe delimiter when data contains commas
  • ☐Format with TOON Formatter before final use

Tools for Error Resolution

TOON Validator

Get detailed error messages with line numbers

TOON Formatter

Auto-fix indentation and formatting issues

JSON to TOON

Convert from valid JSON to avoid manual errors

TOON to JSON

Verify your TOON by converting to JSON

TOON Viewer

Visualize structure to spot issues

JSON Formatter

Format source JSON before conversion

External Resources

Back to TOON ArticlesAll Categories