# How to Submit Bug Reports for WeatherNext: A Complete Guide

> Learn how to submit bug reports for WeatherNext effectively. Follow our guide for clear instructions on using GitHub Issues and email for detailed feedback and issue resolution.

- Repository: [Google DeepMind/weathernext](https://github.com/google-deepmind/weathernext)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Bug reports for WeatherNext should be submitted via GitHub Issues with detailed environment information, reproduction steps, and logs; urgent or private issues can be emailed to weathernext@google.com.**

The WeatherNext repository by Google DeepMind provides state-of-the-art weather forecasting models. When you encounter problems with model loading, inference, or data processing, following the project's established bug reporting workflow ensures maintainers can diagnose and resolve issues efficiently.

## Using GitHub Issues for WeatherNext Bug Reports

GitHub Issues is the primary channel for bug reports in the `google-deepmind/weathernext` repository. The process leverages standard GitHub workflows with project-specific templates.

### Creating a New Issue

Navigate to the repository's **Issues** tab and click **New issue**. If the repository includes an issue template at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/google-deepmind/weathernext/blob/main/.github/ISSUE_TEMPLATE/bug_report.md), GitHub will pre-fill the form automatically. When no template appears, create your issue manually with a descriptive title following this pattern:

```

Bug: [Brief description] in [WeatherNext component]

```

Example: "Bug: Crash when loading WeatherNext Cyclones Mini on GPU"

### Required Information in Your Bug Report

Every effective bug report should include these components:

- **Environment** – Operating system, Python version, JAX version, hardware type (TPU/GPU/CPU), and relevant environment variables
- **Model & Data** – Specific checkpoint used (e.g., `WeatherNextCyclones_Mini_<2024>`), data source (ERA5, HRES, IBTrACS), and custom configuration files
- **Reproduction Steps** – Exact commands or notebook cells that trigger the bug, ideally as a minimal, self-contained script
- **Observed vs. Expected Behavior** – Error messages, incorrect outputs, and what should have happened instead
- **Logs & Stack Traces** – Full traceback pasted directly into the issue or attached as files
- **Additional Context** – Screenshots, notebook links, or references to recent code changes

## Minimal Reproduction Script Example

Include runnable Python code in your bug report. This example demonstrates loading a WeatherNext Cyclones Mini checkpoint and triggering a rollout that may fail:

```python

# Minimal script that reproduces a crash when loading a Cyclones Mini checkpoint

import weathernext
from weathernext.utils import model_utils

# Load the model (replace with the exact checkpoint you used)

model = model_utils.load_model(
    checkpoint_path="WeatherNextCyclones_Mini_<2024>.npz",
    config_path="weathernext/weathernext2/configs/WeatherNextCyclones_Mini.json",
)

# Attempt a rollout that caused the bug

try:
    forecast = model.rollout(initial_state, steps=10)
except Exception as e:
    print("Error during rollout:", e)
    raise

```

Adjust paths and parameters to match your specific setup before pasting into the *Reproduction Steps* section.

## Alternative Contact Methods

For urgent security issues or bugs containing sensitive information, email the project directly at **weathernext@google.com**. Include the same detailed information required for GitHub Issues. This contact information is documented in the [README.md contact section](https://github.com/google-deepmind/weathernext/blob/main/README.md#contact).

## After Submitting Your Bug Report

Once submitted, monitor the issue for:

- Triage comments from maintainers requesting clarification
- Labels applied to categorize priority and component
- Linked pull requests that implement fixes
- Requests to verify resolved issues

Respond promptly to maintainers' questions and test proposed fixes when available.

## Key Reference Files

The following files in the `google-deepmind/weathernext` repository provide authoritative guidance:

- **[`CONTRIBUTING.md`](https://github.com/google-deepmind/weathernext/blob/main/CONTRIBUTING.md)** – Guidelines for contributions, code reviews, and community standards
- **[`README.md`](https://github.com/google-deepmind/weathernext/blob/main/README.md)** – Contact information and project overview
- **[`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/google-deepmind/weathernext/blob/main/.github/ISSUE_TEMPLATE/bug_report.md)** – Default template for structured bug reports (if present in the repository)

## Summary

- **GitHub Issues** is the standard channel for WeatherNext bug reports
- Include **environment details**, **model checkpoint info**, and **reproduction steps** in every report
- Provide **minimal, runnable code** that demonstrates the bug
- Use **`weathernext@google.com`** for urgent or private issues only
- Reference **[`CONTRIBUTING.md`](https://github.com/google-deepmind/weathernext/blob/main/CONTRIBUTING.md)** and the **README contact section** for official project policies

## Frequently Asked Questions

### Does WeatherNext provide a bug report template?

If [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/google-deepmind/weathernext/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) exists in the repository, GitHub automatically displays it when you create a new issue. The template prompts for environment information, reproduction steps, and expected behavior. When no template is present, follow the structured format described in this guide.

### What model checkpoint information should I include?

Specify the exact checkpoint filename, such as `WeatherNextCyclones_Mini_<2024>.npz` or `WeatherNextTroposphere_Base.npz`, along with the configuration file path from `weathernext/weathernext2/configs/`. Also note whether you modified any default hyperparameters or used custom training weights.

### How do I report performance issues versus correctness bugs?

Performance issues—slow inference, high memory usage, TPU/GPU utilization problems—should be reported via GitHub Issues with profiling data, hardware specifications, and batch size configurations. Correctness bugs involving wrong predictions or crashes require reproduction scripts and comparison against expected outputs from the model documentation.

### Will maintainers respond to incomplete bug reports?

Incomplete reports lacking reproduction steps or environment details may be labeled **needs-info** or closed after a period of inactivity. The WeatherNext team prioritizes actionable reports that demonstrate reproducible problems, as these require less back-and-forth to diagnose.