# How to Report a Bug in Marin: A Step-by-Step Guide to Contributing Issues

> Learn how to report a bug in the marin-community/marin repository effectively. Follow our step-by-step guide to create detailed bug reports and contribute to Marin's development.

- Repository: [The Marin Project/marin](https://github.com/marin-community/marin)
- Tags: how-to-guide
- Published: 2026-08-27

---

**Report bugs in the marin-community/marin repository by searching existing issues first, preparing a minimal reproducible example with your specific environment details, and submitting a structured report via GitHub's issue templates.**

The Marin machine learning training framework relies on detailed bug reports to maintain stability across its distributed components. When you report a bug in Marin, you help improve tools like the `StepRunner` execution engine and the `train_lm` training pipeline. Following the contribution guidelines documented in [`CONTRIBUTING.md`](https://github.com/marin-community/marin/blob/main/CONTRIBUTING.md) and [`docs/dev-guide/contributing.md`](https://github.com/marin-community/marin/blob/main/docs/dev-guide/contributing.md) ensures your issue receives prompt attention from maintainers.

## Verify the Bug Has Not Been Reported

Before creating a new issue, search the existing issue tracker to avoid duplicates. The Marin repository uses GitHub Issues for all bug tracking.

Use the GitHub CLI to search for open bugs:

```bash
gh issue list --search "bug" --state open

```

Review both open and closed issues to ensure your specific configuration—whether involving TPU allocation, YAML configuration parsing, or gradient checkpointing—has not already been addressed.

## Prepare a Minimal Reproducible Example

A high-quality Marin bug report requires a minimal script that reliably triggers the failure. Your reproduction case should isolate the problem from your larger training pipeline.

Include these critical environment details:

- **Marin version**: Run `git rev-parse HEAD` to capture the exact commit hash
- **Python version**: Marin requires **Python 3.12**; verify with `python --version`
- **Hardware configuration**: Specify CPU, GPU, or TPU details including device counts
- **Configuration files**: Provide excerpts from [`marin.yaml`](https://github.com/marin-community/marin/blob/main/marin.yaml) or other relevant configs

Here is an example minimal reproduction script that demonstrates a bug in the step execution layer:

```python
from marin.execution.step_runner import StepRunner
from marin.experiment.train import train_lm
from experiments.llama import llama_nano

# Minimal case that fails on TPU #3

model = train_lm(
    name="checkpoints/bug-demo",
    version="v0",
    model=llama_nano,
    optimizer=None,
    datasets={},  # Empty to provoke the bug

    batch_size=2,
    seq_len=2048,
    num_train_steps=10,
    resources="tpu",
)
StepRunner().run([model])

```

## Create a Bug Report via GitHub

Marin provides structured issue templates in `.github/ISSUE_TEMPLATE/` that automatically load when you create a new bug report. You can submit via the web interface or command line.

**Web Interface**: Navigate to **Issues → New Issue → Bug report** in the marin-community/marin repository.

**CLI Method**: Use the `gh` command to create a labeled issue with a formatted body:

```bash
gh issue create \
    --title "Bug: <short description>" \
    --label bug \
    --body "$(cat <<'EOF'
**Description**
Concise summary of unexpected behavior.

**Reproduction**

```bash
uv run python -m marin ...

```

Minimal config:

```yaml

# marin.yaml excerpt

```

**Expected behavior**
What should happen.

**Actual behavior**
What happens instead (include traceback).

**Environment**
- Python: 3.12.x
- Marin commit: $(git rev-parse HEAD)
- Hardware: <CPU/GPU/TPU details>
EOF
)"

```

## Follow the Issue Template Structure

The repository's issue template enforces a standard format that covers **Description**, **Steps to Reproduce**, **Expected vs. Actual Behavior**, and **Environment**. Populate each section clearly, referencing specific file paths like [`marin/execution/step_runner.py`](https://github.com/marin-community/marin/blob/main/marin/execution/step_runner.py) or [`marin/experiment/train.py`](https://github.com/marin-community/marin/blob/main/marin/experiment/train.py) where applicable.

After submission, the issue receives automatic labels and assignment to component teams such as `levanter`, `iris`, or `zephyr`. The `.github/workflows/` directory contains CI pipelines that may run automated tests against your reported state to validate the reproduction.

## Submit Patches with Pull Requests

If you implement a fix, open a pull request that references the bug issue using the `Fixes #1234` syntax. Include a summary of the root cause and how your changes resolve it, linking back to the original bug report for context.

## Summary

- **Search first**: Use `gh issue list` to check for existing reports before filing duplicates
- **Environment matters**: Always include `git rev-parse HEAD`, Python 3.12 version, and hardware specs
- **Minimal examples**: Isolate bugs using imports from `marin.execution.step_runner` and related modules
- **Structured reports**: Use the GitHub issue templates in `.github/ISSUE_TEMPLATE/` for consistent formatting
- **Reference issues**: Link PRs to bugs with "Fixes #" notation to auto-close resolved tickets

## Frequently Asked Questions

### What information is required for a Marin bug report?

You must provide the Marin commit hash (via `git rev-parse HEAD`), confirmation you are using **Python 3.12**, hardware specifications including TPU or GPU details, and a minimal code snippet or configuration that reproduces the error. The issue templates in `.github/ISSUE_TEMPLATE/` enforce these requirements.

### How do I check if my bug has already been reported in Marin?

Use the GitHub CLI command `gh issue list --search "bug" --state open` to browse existing issues, or check closed issues to see if the problem was resolved in a recent commit. The [`CONTRIBUTING.md`](https://github.com/marin-community/marin/blob/main/CONTRIBUTING.md) file recommends this search step to prevent duplicate submissions.

### Can I submit a bug fix directly without creating an issue first?

While you can open a pull request directly, the [`docs/dev-guide/contributing.md`](https://github.com/marin-community/marin/blob/main/docs/dev-guide/contributing.md) guidelines recommend creating an issue first to discuss the bug with maintainers. This ensures the fix aligns with the project's architecture and prevents wasted effort on changes that may conflict with ongoing refactoring.

### What labels are automatically applied to new Marin bug reports?

Issues created with the "Bug report" template automatically receive the `bug` label and are routed to component teams like `levanter`, `iris`, or `zephyr` based on the file paths mentioned in your report. The `.github/workflows/` automation handles this triage based on keywords in your submission.