Troubleshooting

Troubleshooting & Common Pitfalls 🧯

Parsing errors (FormatException)

• Symptom: FormatException: Invalid size format
• Causes:
  • Typos or unknown symbols (e.g., XB)
  • JEDEC/IEC mismatch (e.g., KiB parsed under SI)
• Fixes:
  • Ensure standard matches your input: si | iec | jedec
  • Use full-form words when unsure (e.g., megabytes, kibibytes)

Negative values

• ByteConverter(-1) or parsing a negative size throws ArgumentError.
• Ensure upstream inputs are sanitized before parsing.

Bits vs Bytes confusion

• Lowercase b denotes bits; uppercase B denotes bytes.
• Using useBytes: false formats values in bits; set useBytes: true to force bytes.

Forced unit doesn’t change scale

• forceUnit pins the unit (e.g., MB, MiB, Gb) and disables auto-scaling.
• When using bits, byte units are mapped to bit units where possible (e.g., KB -> Kb).

Locale formatting

• Use separator (e.g., ,) and spacer (e.g., empty string) to control visuals.
• minimumFractionDigits/maximumFractionDigits override precision rounding style.

Data rates

• DataRate.parse('1 MB/s', standard: ByteStandard.iec) will throw (unit inconsistent with IEC).
• Prefer DataRate.parse('1 MiB/s', standard: ByteStandard.iec) for IEC.

Very large values

• Prefer BigByteConverter for exact integer math at EB/ZB/YB scales.
• Use parseByteSizeAuto to decide automatically.

Debugging tips

• Log the normalized number/string or run with simpler inputs (e.g., remove grouping) to isolate issues.
• Cross-check with tests in test/ for expected behaviors and edge cases.