# How to Report a Bug in Graphify: Complete Guide with Examples > Learn how to report a bug in Graphify effectively. This guide details collecting input files and cache entries to submit clear GitHub issues with examples. - Repository: [Graphify Labs/graphify](https://github.com/Graphify-Labs/graphify) - Tags: how-to-guide - Published: 2026-07-19 --- **To report a bug in Graphify, collect the input file and the specific cache entry from `graphify-out/cache/`, then submit a GitHub issue containing the reproduction command, observed behavior, and expected results.** Graphify is an open-source extraction and analysis tool maintained by Graphify-Labs. When the parser fails to capture nodes, generates incorrect edges, or crashes on specific inputs, submitting a detailed bug report ensures maintainers can reproduce the issue efficiently. Understanding how to report a bug in Graphify according to the project's official guidelines—documented in [`README.md`](https://github.com/Graphify-Labs/graphify/blob/main/README.md) at line 837—accelerates the triage process. ## Required Artefacts for a Complete Bug Report The Graphify maintainers require two critical files to investigate extraction failures: the original input file and the corresponding cache entry generated by the core extraction logic. ### Input File and Cache Entry Every bug report must include: - The **input file** (source code, PDF, image, etc.) that triggers the bug - The **cache entry** located under `graphify-out/cache/` (e.g., `graphify-out/cache/.json`). This file contains the intermediate representation generated by [`graphify/out/__init__.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/out/__init__.py) and is essential for reproducing parsing errors. As stated in the [`README.md`](https://github.com/Graphify-Labs/graphify/blob/main/README.md): *"Extraction bugs — open an issue with the input file, the cache entry (`graphify-out/cache/`), and what was missed or wrong."* ### Environment Context Include your operating system, Python version, and Graphify version (run `graphify --version`). If the bug involves a specific language extractor (e.g., Rust, Objective-C), mention this explicitly, as different extractors may trigger unique code paths in the extraction pipeline. ## Step-by-Step Guide to Reporting Bugs Follow this workflow to ensure your issue contains actionable information for the maintainers: 1. **Gather artefacts**: Locate your input file and the cache file created in `graphify-out/cache/` after running the extraction command. The cache contains the serialized graph state produced by the extraction engine. 2. **Open a GitHub issue**: Navigate to `https://github.com/Graphify-Labs/graphify/issues` and click **"New issue"**. Select the bug report template if available. 3. **Complete the description**: - **Brief summary**: One sentence describing the problem - **Steps to reproduce**: The exact command executed (e.g., `graphify extract ./file.ts --lang ts`) - **Observed behavior**: Error messages or incorrect graph output - **Expected behavior**: The correct node structure or successful extraction - **Attachments**: Upload both the input file and the cache entry 4. **Add technical context**: Reference relevant source files if known. Bugs involving duplicate node IDs often relate to [`graphify/ids.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/ids.py), while cache staleness issues connect to [`graphify/watch.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/watch.py). API-related bugs may involve [`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py). 5. **Submit**: Post the issue for triage. The maintainers will analyze the cache entry to trace the issue through the extraction pipeline. ## Bug Report Templates and Examples Use these concrete examples to structure your report according to the source code requirements. ### Example 1: Missing TypeScript Nodes When class or method nodes fail to appear in the output: ```bash # Command you ran graphify extract ./examples/bad.ts --lang ts # Expected: nodes for class `Foo` and method `bar` # Observed: only the file node appears ``` **Attachments**: Include [`bad.ts`](https://github.com/Graphify-Labs/graphify/blob/main/bad.ts) and `graphify-out/cache/8f3c9e…json`. ### Example 2: PDF Extraction Failure When processing documents triggers encoding errors: ```bash graphify extract ./docs/report.pdf --lang pdf # Expected: a `document` node with extracted text # Observed: the command fails with `UnicodeDecodeError` ``` **Attachments**: Include `report.pdf` and `graphify-out/cache/d2a4b1…json`. ## Summary - **Always attach** the input file and the corresponding `graphify-out/cache/` entry to every bug report, as required by the guidelines in [`README.md`](https://github.com/Graphify-Labs/graphify/blob/main/README.md) at line 837. - **Structure your issue** with reproduction steps, observed behavior, and expected behavior to help maintainers trace the logic in [`graphify/out/__init__.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/out/__init__.py). - **Reference the source**: Key files like [`graphify/ids.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/ids.py) (node ID generation) and [`graphify/watch.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/watch.py) (cache resolution) help maintainers locate the root cause. - **Check translations**: The Chinese translation of the guidelines exists in [`docs/translations/README.zh-CN.md`](https://github.com/Graphify-Labs/graphify/blob/main/docs/translations/README.zh-CN.md) at line 222. ## Frequently Asked Questions ### What should I do if Graphify doesn't create a cache file? If the crash occurs before cache generation in `graphify-out/cache/`, submit the input file and the complete error traceback. Include your environment details and the exact command used. However, most extraction bugs require the cache entry for analysis, so verify the cache directory exists after the failure, as the core extraction logic in [`graphify/out/__init__.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/out/__init__.py) typically generates these files before final output. ### Can I report bugs for the HTTP API server? Yes. Bugs affecting the server endpoints should reference [`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py) and include the HTTP request payload along with the server logs. If the issue involves cached data served via the API, include the relevant cache entry from `graphify-out/cache/` to help reproduce the serialization error. ### How do I report bugs in watch mode? For issues specific to file watching or incremental updates, mention [`graphify/watch.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/watch.py) in your report. Include steps showing how the cache becomes stale or fails to update when source files change, along with the cache entries before and after the observed behavior. This helps maintainers debug the cache resolution logic. ### Where are the official bug reporting guidelines documented? The primary guidelines reside in [`README.md`](https://github.com/Graphify-Labs/graphify/blob/main/README.md) at line 837 of the Graphify-Labs/graphify repository. A Chinese translation is available in [`docs/translations/README.zh-CN.md`](https://github.com/Graphify-Labs/graphify/blob/main/docs/translations/README.zh-CN.md) at line 222. Both documents explicitly require the input file and cache entry for all extraction bug reports.