---
id: parse-errors
version: "0.5.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# parse-errors — re-raise parse errors with filename and line number

License: permissive · Maintenance: active · Downloads: 191.1K/mo

## What it is and what it does

parse-errors is a thin wrapper around config file parsing that intercepts exceptions and enriches them with precise source locations. When you parse JSON, TOML, or YAML inside a ParseContext, any exception that occurs gets analyzed for line and column information and re-raised as a ParseError with the filename, line, and column attached. If location information cannot be extracted, the original exception passes through unchanged.

The package depends on tree-sitter and tree-sitter-toml for syntax-aware parsing, pyyaml for YAML support, and json-source-map for JSON location tracking. It's designed for developers building tools that parse user-supplied config files and need to give users actionable error messages pointing to the exact spot in the file that caused the problem.

Use it for:

- CLI tools that load JSON, TOML, or YAML config files and need to report parse errors with precise line/column to users.
- Configuration validation frameworks that combine multiple decoders and want unified error reporting.
- Build systems or deployment tools that must pinpoint config syntax errors for quick user fixes.
- API servers that accept config uploads and need to reject invalid files with exact error locations.
- Development utilities that parse structured data and want better debugging output than bare exception messages.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Wraps parse and validation errors from JSON, TOML, and YAML files to include filename, line number, and column in the exception, making it easier to report precise error locations to users.

Yes, if you parse config files (JSON, TOML, YAML) and want to give users precise error locations. Low install friction, permissive license, no known vulnerabilities, and active maintenance. The package is young (first release 2026-03-18) but solves a real UX problem. Install it if error reporting quality matters in your use case.

## Install

pip install parse-errors
uv add parse-errors
poetry add parse-errors

## Installing parse-errors

Before you install: Low friction: pure Python wheel with four runtime dependencies (json-source-map, pyyaml, tree-sitter, tree-sitter-toml). Active maintenance as of 2026-05-01, though early in its release history (first release 2026-03-18).

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal obligations—suitable for any project type.

Quickstart:

from parse_errors import ParseContext, ParseError

with ParseContext("config.toml", data=raw, format="toml"):
    data = tomllib.loads(raw.decode())
    config = msgspec.convert(data, Config)

Requires Python 3.10 or later.

Verify before relying:

- Whether tree-sitter-toml binary wheels are available for all target platforms, or if compilation is required.
- Performance impact of tree-sitter parsing overhead on large config files.
- Exact behavior when format inference from filename extension fails or is ambiguous.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 191.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

parse error location reporting, config file error messages, json toml yaml error handling, validation error with line numbers, file parsing error context, toml syntax error location, config parsing exceptions, error-handling, config-parsing, developer-tools

[View on SkillFed](https://skillfed.io/packages/parse-errors) · [View on PyPI](https://pypi.org/project/parse-errors/)