parsing errors

Guide for parsing errors

Troubleshooting Data Parsing Errors

Common Parsing Errors

Error 1: Type Mismatch (String vs u32)

Error Message:
ERROR Failed to parse rocks: invalid type: string "copper_ore", expected u32 at line 8 column 35
Cause: Rust struct expects u32 but JSON provides String.
Solution: Update Rust struct to use String:
  pub struct RockData {
-     pub ore_item_id: u32,
+     pub ore_item_id: String,
  }
Related Files:
  • src/systems/skills/mining.rs
  • src/systems/skills/woodcutting.rs
  • src/systems/tutorial.rs

Error 2: Enum Variant Mismatch

Error Message:
ERROR Failed to parse tutorials: invalid type: unit variant, expected struct variant at line 13 column 46
Cause: JSON uses unit variant format for struct variant (or vice versa).
Solution: Match JSON format to Rust enum definition:
If Rust has struct variant:
Custom { event_id: String }
JSON should be:
{
    "Custom": {
        "event_id": "click_anywhere"
    }
}
If Rust has unit variant:
AttackEnemy
JSON should be:
"AttackEnemy"

Error 3: Missing Required Field

Error Message:
ERROR Failed to parse: missing field `required_field` at line 10
Cause: JSON is missing a required field from the Rust struct.
Solution: Either:
  1. Add the field to JSON
  2. Make the field optional in Rust:
    pub required_field: Option<String>,

Error 4: Invalid PNG Signature

Error Message:
ERROR Failed to load asset 'logos/Guide_icon.png': Format error decoding Png: Invalid PNG signature.
Cause: File has .png extension but is actually a JPEG.
Solution:
  1. Verify file type: file assets/logos/Guide_icon.png
  2. Rename to correct extension: mv Guide_icon.png Guide_icon.jpg
  3. Update code references

Debugging Workflow

Step 1: Identify the Error

Run the game and capture error output:
cargo run --bin legends_client 2>&1 | tee error.log
Look for lines starting with ERROR or Failed to parse.

Step 2: Locate the Problem

The error message typically includes:
  • File name: Which JSON file failed
  • Line/column: Where the error occurred
  • Expected vs actual: What type was expected
Example:
ERROR Failed to parse rocks: invalid type: string "copper_ore", expected u32 at line 8 column 35
This tells us:
  • File: mining_rocks.json
  • Location: Line 8, column 35
  • Problem: String where u32 expected

Step 3: Check JSON File

Open the JSON file and navigate to the error location:
cat -n data/mining_rocks.json | head -n 10

Step 4: Check Rust Struct

Find the corresponding Rust struct:
grep -r "struct RockData" src/
Compare field types between JSON and Rust.

Step 5: Apply Fix

Choose the appropriate fix:
  • Update Rust struct type
  • Update JSON data format
  • Add missing fields
  • Fix enum variant format

Step 6: Verify

Recompile and run:
cargo check
cargo run --bin legends_client
Check logs for success message:
INFO Loaded 8 rock types

Prevention Strategies

1. Schema Validation

Create JSON schemas for data files:
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "rock_id": {"type": "string"},
      "ore_item_id": {"type": "string"}
    },
    "required": ["rock_id", "ore_item_id"]
  }
}

2. Unit Tests

Add tests for data parsing:
#[test]
fn test_parse_rocks() {
    let json = r#"[
        {
            "rock_id": "copper_rock",
            "ore_item_id": "copper_ore"
        }
    ]"#;
    
    let rocks: Vec<RockData> = serde_json::from_str(json).unwrap();
    assert_eq!(rocks.len(), 1);
}

3. Consistent Naming

Follow naming conventions:
  • Use snake_case for field names
  • Use String for all IDs
  • Document enum variant types

4. Version Control

Commit Rust struct changes and JSON updates together to maintain consistency.

Quick Reference

Error TypeLikely CauseFix Location
expected u32, found stringType mismatchRust struct
expected struct variant, found unitEnum formatJSON file
missing fieldRequired field absentJSON file or Rust struct
Invalid PNG signatureWrong file extensionAsset file
unknown fieldExtra field in JSONRemove from JSON or add to Rust

Related Documentation