Stirling-Tools/Stirling-PDF · warning · SystemExit

File not found: {json_path}

Error message

File not found: {json_path}

What it means

SystemExit raised by the analyze_pdf_json.py CLI when the supplied json_path does not exist on the filesystem. This is a pre-flight validation check before attempting to open/parse the file.

Source

Thrown at scripts/analyze_pdf_json.py:211

    return DocumentBreakdown(
        total_bytes=total_size,
        fonts=font_stats,
        pages=page_stats,
        metadata_bytes=approx_struct_size(metadata),
        xmp_bytes=base64_payload_size(document.get("xmpMetadata")),
        form_fields_bytes=approx_struct_size(document.get("formFields")),
        lazy_flag_bytes=approx_struct_size(document.get("lazyImages")),
    )


def main() -> None:
    parser = argparse.ArgumentParser(description="Inspect a PDF JSON export.")
    parser.add_argument("json_path", type=Path, help="Path to the JSON export.")
    args = parser.parse_args()

    json_path = args.json_path
    if not json_path.exists():
        raise SystemExit(f"File not found: {json_path}")

    file_size = json_path.stat().st_size
    print(f"File: {json_path}")
    print(f"Size: {human_bytes(file_size)} ({file_size:,} bytes)")

    with json_path.open("r", encoding="utf-8") as handle:
        document = json.load(handle)

    if not isinstance(document, dict):
        raise SystemExit("Unexpected JSON structure (expected an object at root).")

    summary = analyze_document(document, file_size)
    page_stats = summary.pages
    print(f"Pages: {page_stats.page_count}")
    print(f"Total text elements: {page_stats.total_text_elements:,}")
    print(f"Total image elements: {page_stats.total_image_elements:,}")
    print(
        f"Page structural bytes (text arrays + images + streams + annotations): "

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Verify the file exists: ls -la <path> before running.
2. Use an absolute path to avoid working-directory confusion.
3. Generate the JSON export first (export from the PDF text editor) if it does not exist.

# Validate before invoking the analyzer
import sys
from pathlib import Path
p = Path(sys.argv[1])
if not p.exists():
    print(f"Not found: {p}", file=sys.stderr); sys.exit(1)

When it happens

Trigger: Running 'python scripts/analyze_pdf_json.py <path>' where <path> points to a nonexistent file — typo, wrong relative path, or the export was never generated.

Common situations: Typo in the path argument. Running from the wrong working directory (relative path mismatch). The PDF JSON export was never produced or was deleted.

Related errors

• No PDF files found under the supplied --input paths.
• Unexpected JSON structure (expected an object at root).
• No URLs supplied. Use --urls and/or --urls-file.
• The 'tomlkit' library is not installed. Please install it us
• Failed to parse {path}: {exc}

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/d4597296f4ed2889. Report an issue: GitHub.