agent couldn't parse the usage CSV export, run failed

TL;DR

Inspect the actual bytes: encoding, delimiter, and header row. Then parse with the detected settings, validate headers against expectations, and fail loudly on unexpected shapes instead of producing wrong numbers.

agent couldn't parse the usage CSV export, run failed

Use this when

• A usage CSV export fails to parse in the agent's code.
• The parser assumed comma and UTF-8.
• The vendor recently changed the export.

Not for this skill when

• The export is empty. That is a data problem.
• The export is truncated. Fix the export first.
• The parse succeeds but counts are wrong. Validate the logic, not the parse.

Steps

1. Dump the first bytes of the file and detect the encoding. Verify: you know the real encoding.
2. Identify the actual delimiter; it is not always a comma. Verify: the delimiter is confirmed.
3. Parse with the detected encoding and delimiter. Verify: the parse completes.
4. Validate the headers match expectations. Verify: every expected column exists.
5. Check row counts for sanity. Verify: the totals are plausible.

Variant phrasings

CSV parse failed

The short phrasing.

usage export unreadable

The symptom-first search.

encoding error CSV

The cause-first phrasing.

Compatibility: Any usage CSV export parsed by agent code.

Why it happens

Vendors change encodings and delimiters without notice, and parsers that assume comma plus UTF-8 break. The failure is in the assumption, not the data.

Edge cases / pitfalls

• Semicolon delimiters in European locales; detect, do not assume.
• Header rows that shift position or wording between exports; validate, do not index blindly.
• The file being fine but the agent reading it with the wrong mode; check binary versus text handling.
• Failing loudly matters: a parser that guesses wrong silently is worse than one that errors.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_9IE5kh0JJDReLRHaHcvU5A