# How to Report Bugs or Suggest Features for Olmocr: A Complete Guide

> Report bugs or suggest features for olmocr. File structured GitHub Issues in the allenai/olmocr repository using provided templates. Get your issues resolved faster.

- Repository: [Ai2/olmocr](https://github.com/allenai/olmocr)
- Tags: how-to-guide
- Published: 2026-07-08

---

**Report bugs or suggest features for olmocr by filing structured GitHub Issues in the allenai/olmocr repository using the provided templates for bug reports and feature requests.**

The **allenai/olmocr** repository uses GitHub's standard issue tracking system to manage community feedback. Whether you have encountered an error in the OCR pipeline or want to propose new functionality, the project provides specific templates and guidelines to ensure your report reaches the maintainers efficiently.

## Where to Report Bugs and Suggest Features

All bug reports, feature requests, and documentation suggestions should be submitted as **GitHub Issues** in the main repository. The project maintains separate templates to streamline the triage process and ensure you provide the necessary context.

### Filing Bug Reports

To report a bug, use the dedicated template at the bug report URL:

<https://github.com/allenai/olmocr/issues/new?template=bug_report.yml>

This template, defined in [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/allenai/olmocr/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml), automatically prompts you for environment details, reproduction steps, and expected versus actual behavior. Providing complete information allows the maintainers to reproduce and resolve issues faster.

### Submitting Feature Requests

For new functionality or enhancements, use the feature request template:

<https://github.com/allenai/olmocr/issues/new?template=feature_request.yml>

The template in [`.github/ISSUE_TEMPLATE/feature_request.yml`](https://github.com/allenai/olmocr/blob/main/.github/ISSUE_TEMPLATE/feature_request.yml) asks for a description of the proposed feature, use cases, and potential implementation approaches. This structure helps the team evaluate how the suggestion fits into the project's roadmap.

## Contribution Guidelines and Templates

Before opening any issue, review the guidelines in [`.github/CONTRIBUTING.md`](https://github.com/allenai/olmocr/blob/main/.github/CONTRIBUTING.md) (<https://github.com/allenai/olmocr/blob/main/.github/CONTRIBUTING.md>). This file outlines the project's standards for reporting issues, code style, testing requirements, and the pull request process.

Selecting the appropriate template automatically adds the required sections to your issue, making it easier for maintainers to categorize and prioritize your feedback. If you have quick questions or need clarification before filing a formal issue, you can start a discussion in the **Discussions** tab of the repository, though the Issues system remains the primary channel for bugs and feature proposals.

## Programmatically Creating Issues

You can automate issue creation using the GitHub CLI or API when reporting bugs or suggesting features for olmocr at scale.

### Using the GitHub CLI

Create a bug report from the command line using the `gh` CLI:

```bash
gh issue create \
  --repo allenai/olmocr \
  --title "OCR fails on multi‑column tables in PDF X" \
  --body "$(cat <<EOF
**Bug Description**
The OCR output merges columns in multi‑column tables for PDF X.

**Steps to Reproduce**
1. Run `olmocr pipeline --input path/to/pdf_x.pdf`
2. Observe the merged columns in the generated markdown.

**Environment**
- OS: Ubuntu 22.04
- Python: 3.11
- OLMOCR version: 0.4.2

**Expected Behavior**
Each column should be preserved separately.

**Actual Behavior**
Columns are concatenated into a single column.
EOF
)" \
  --label bug

```

### Using the GitHub API

Submit a feature request via `curl` using the GitHub REST API:

```bash
curl -X POST \
  -H "Authorization: token <YOUR_PERSONAL_ACCESS_TOKEN>" \
  -d '{
    "title": "Add support for OCR of handwritten equations",
    "body": "**Feature Description**\nEnable detection and LaTeX rendering of handwritten mathematical expressions.\n\n**Use Cases**\n- Academic papers with handwritten notes\n- Scanned lecture slides\n\n**Potential Approach**\nLeverage a specialized handwriting model (e.g., MathPix) and integrate it as a post‑processing step.\n",
    "labels": ["enhancement"]
  }' \
  https://api.github.com/repos/allenai/olmocr/issues

```

Replace `<YOUR_PERSONAL_ACCESS_TOKEN>` with a token that has the `repo` scope.

## Summary

- **Use GitHub Issues** as the primary channel to report bugs or suggest features for olmocr, located at <https://github.com/allenai/olmocr/issues>.
- **Select appropriate templates** via the bug report or feature request URLs to ensure your submission includes required context.
- **Review [`.github/CONTRIBUTING.md`](https://github.com/allenai/olmocr/blob/main/.github/CONTRIBUTING.md)** before submitting to understand project standards and expectations.
- **Automate submissions** using the GitHub CLI or REST API when creating multiple issues programmatically.

## Frequently Asked Questions

### Where do I report bugs for olmocr?

Report bugs by creating a GitHub Issue in the allenai/olmocr repository using the bug report template at <https://github.com/allenai/olmocr/issues/new?template=bug_report.yml>. This template, stored in [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/allenai/olmocr/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml), ensures you provide environment details and reproduction steps necessary for the maintainers to investigate.

### How do I suggest a new feature for olmocr?

Submit feature requests through the feature request template at <https://github.com/allenai/olmocr/issues/new?template=feature_request.yml>. The template defined in [`.github/ISSUE_TEMPLATE/feature_request.yml`](https://github.com/allenai/olmocr/blob/main/.github/ISSUE_TEMPLATE/feature_request.yml) guides you to describe use cases and potential implementation approaches, helping the team evaluate your proposal against the project roadmap.

### What information should I include in a bug report?

Include your operating system, Python version, olmocr version, a clear description of the bug, step-by-step reproduction instructions, expected behavior, and actual behavior. The bug report template automatically prompts for these details, following the guidelines established in [`.github/CONTRIBUTING.md`](https://github.com/allenai/olmocr/blob/main/.github/CONTRIBUTING.md).

### Can I use the GitHub API to create issues programmatically?

Yes, you can create issues using the GitHub CLI (`gh issue create`) or the REST API (`POST /repos/allenai/olmocr/issues`) with a personal access token containing the `repo` scope. This approach is useful for automated reporting or when submitting multiple related issues, though you should still follow the template structure for consistency.