Troubleshooting
This page documents common issues and their solutions when using zzson, particularly with WebAssembly bindings.
WebAssembly Issues
Objects Parsing to Empty Results
Issue: Parsed JSON objects appear empty ({}
) even when the input contains valid data like {a:1}
or {"a":1}
.
Symptoms:
Object.keys(result)
returns an empty arrayJSON.stringify(result)
returns"{}"
- Property access on parsed objects returns
undefined
- Browser console shows results as
Map(1)
instead of plain objects
Root Cause: This was a critical bug in versions prior to 1.2.4 where the WebAssembly bindings used serde_wasm_bindgen::to_value()
which converted Rust HashMap
objects to JavaScript Map
objects instead of plain JavaScript objects.
Solution:
- Fixed in version 1.2.4: The WebAssembly bindings now use a custom
value_to_js()
function that creates proper JavaScript objects - If using an older version: Upgrade to version 1.2.4 or later
Technical Details: The fix involved replacing the automatic serde conversion with manual object creation:
// Before (problematic):
serde_wasm_bindgen::to_value(&value)
// After (fixed):
value_to_js(&value) // Custom function using js_sys::Object
Browser Caching of WASM Modules
Issue: Changes to the WASM module are not reflected in the browser even after rebuilding.
Solution:
- Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
- Clear browser cache
- Add cache-busting query parameters to module imports:
import init from './pkg/zzson.js?v=' + Date.now();
WASM Module Loading Failures
Issue: WebAssembly module fails to load with network errors.
Common Causes & Solutions:
- Incorrect MIME type: Ensure your web server serves
.wasm
files withapplication/wasm
MIME type - CORS issues: Serve files from a proper HTTP server, not file:// protocol
- Path issues: Verify the path to
pkg/zzson.js
andpkg/zzson_bg.wasm
is correct
Testing Setup: Use a simple HTTP server for testing:
# Python 3
python -m http.server 8080
# Node.js (with http-server package)
npx http-server -p 8080
# Rust (with basic-http-server)
cargo install basic-http-server
basic-http-server docs/ -a 127.0.0.1:8080
Parser Issues
Unquoted Keys Not Working
Issue: JSON with unquoted keys like {key: "value"}
fails to parse.
Solution: Ensure allow_unquoted_keys
is enabled in parser options:
const options = {
allow_unquoted_keys: true,
// ... other options
};
const result = parse_json_with_options(input, options);
Comments Causing Parse Errors
Issue: JSON with comments like // comment
or /* comment */
fails to parse.
Solution: Enable comment support in parser options:
const options = {
allow_comments: true,
// ... other options
};
const result = parse_json_with_options(input, options);
Debug Tools
Browser Console Debugging
Enable debug logging by using the debug builds of the WebAssembly module. Debug messages will appear in the browser console showing:
- Token parsing progress
- Value conversion steps
- Object creation details
Test Pages
The following test pages are available for debugging:
error-debug.html
- Error handling and basic parsing testsconsole-debug.html
- Console output capture and displaytoken-debug.html
- Token-level parsing analysisdeep-debug.html
- Comprehensive parsing verification
Manual Testing
Test parsing functionality manually:
// Test basic object parsing
const result1 = parse_json('{"a": 1}');
console.log('Quoted keys:', result1);
// Test unquoted keys (requires options)
const options = { allow_unquoted_keys: true };
const result2 = parse_json_with_options('{a: 1}', options);
console.log('Unquoted keys:', result2);
// Verify object properties
console.log('Keys:', Object.keys(result2));
console.log('JSON:', JSON.stringify(result2));
Getting Help
If you encounter issues not covered here:
- Check the GitHub Issues
- Review the API documentation
- Examine the test files for usage examples
- Create a new issue with:
- Your zzson version
- Browser and version
- Minimal reproduction case
- Expected vs actual behavior