CS2 demo parse failed: the fix.

Most CS2 demo parse failures have four causes: the file is a CS:GO demo, it is still compressed (.dem.bz2), it was cut short, or a game patch changed the format before your parser caught up. Check the first 8 bytes, decompress, and keep the parser current.

Get a free API key Read the CS2 docs

Check the 8-byte header
Decompress .bz2 first
Update after patches

GET /cs2/stats/players?limit=2200 OK

$ curl "https://api.citoapi.com/api/v1/cs2/stats/players?limit=2" \ -H "x-api-key: $CITO_API_KEY"

{  "success": true,  "data": [    {      "playerName": "donk",      "teamName": "Spirit",      "maps": 556,      "rating": 1.45,      "adr": 97.3    },    {      "playerName": "ZywOo",      "teamName": "Vitality",      "maps": 622,      "rating": 1.39,      "adr": 88.1    }    ...  ]}

The error

What you see

demoparser2: UnknownFile
demoparser2: Source1DemoError
demoinfocs: nextByte: insufficient buffer

What do the demo parser errors mean?

demoparser2 reads the first 8 bytes of the file. PBDEMS2 followed by a zero byte is a CS2 demo. HL2DEMO followed by a zero byte is a CS:GO demo, which raises Source1DemoError. Anything else raises UnknownFile. A file that stops mid-stream raises DemoEndsEarly.

Error	Usual cause
UnknownFile	Still compressed (.dem.bz2), an HTML error page saved as .dem, or not a demo.
Source1DemoError	A CS:GO demo (HL2DEMO header) given to a CS2-only parser.
DemoEndsEarly / ErrUnexpectedEndOfDemo	Truncated: the server had not flushed the whole demo, or the download stopped.
nextByte: insufficient buffer, EntityNotFound, UnknownDemoCmd	A game patch changed the demo format; the parser needs an update.

Why do CS2 demos break parsers so often?

Valve changes the demo format with game updates and does not version it publicly. Parsers find out when demos start failing: demoinfocs-golang issue #610 broke on demos after the 15 October 2025 update and was fixed the same day; demoparser issue #320 broke on 21 April 2026.

How do I fix it?

Check the header before parsing, decompress bz2 downloads, catch the truncated case, and upgrade the parser (demoparser2 0.42.0 and demoinfocs-golang v5.2.0 were current on 2026-10-03) whenever demos from a new patch fail.

Python: pip install demoparser2

import bz2, pathlib
from demoparser2 import DemoParser

def load_demo(path: str) -> str:
    p = pathlib.Path(path)
    head = p.read_bytes()[:8]
    if head[:3] == b"BZh":                     # .dem.bz2: decompress first
        out = p.with_suffix("")
        out.write_bytes(bz2.decompress(p.read_bytes()))
        return load_demo(str(out))
    if head == b"PBDEMS2\x00":
        return str(p)                          # CS2 demo
    if head == b"HL2DEMO\x00":
        raise ValueError("CS:GO demo: use a CS:GO parser (demoinfocs /v3)")
    raise ValueError(f"not a demo, header {head!r} (HTML error page? partial download?)")

parser = DemoParser(load_demo("match.dem.bz2"))
kills = parser.parse_event("player_death", player=["X", "Y"], other=["total_rounds_played"])
print(kills.head())

How does the CS2 API make this error impossible?

For professional matches there is no demo to parse: the CS2 API already holds the parsed result, per-map player stats, rounds and match events, plus the list of demos it tracks. Parsing yourself still makes sense for custom analysis, such as positions or grenade trajectories.

The parsed numbers without a parser

curl -s "https://api.citoapi.com/api/v1/cs2/matches/cs2-match-2398722/player-stats" \
  -H "x-api-key: $CITO_API_KEY"
# kills, deaths, assists, ADR, KAST and rating per player per map

curl -s "https://api.citoapi.com/api/v1/cs2/matches/cs2-match-2398722/demos" \
  -H "x-api-key: $CITO_API_KEY"
# the demos tracked for the match, or why none is available yet

Frequently asked questions

Something missing? Email support@citoapi.com.

Why does demoparser2 say UnknownFile?

The first 8 bytes are not a CS2 demo header. Usually the file is still bz2-compressed or is an HTML error page saved with a .dem name.

Can demoparser2 read CS:GO demos?

No. It raises Source1DemoError for CS:GO (HL2DEMO) files. Use a CS:GO parser such as demoinfocs-golang's /v3 module.

Why did my parser stop working after a CS2 update?

Valve changed the demo format in the patch. Upgrade the parser; maintainers usually ship a fix within days, sometimes the same day.

Do I need to parse demos to get pro player stats?

No. The CS2 API returns per-map player stats for professional matches, already parsed.

See pricing

Build CS2 live score apps

Free is for building and testing. Paid plans add commercial use, real-time live data and the full archive.

Get a free CS2 API key