# How to Report a Bug in GeoLibre: A Complete Guide for Contributors

> Learn how to report a bug in GeoLibre by opening a GitHub issue with clear steps, environment details, and test data. Contribute to improving the opengeos/GeoLibre repository.

- Repository: [Open Geospatial Solutions/GeoLibre](https://github.com/opengeos/GeoLibre)
- Tags: how-to-guide
- Published: 2026-08-16

---

**To report a bug in GeoLibre, open a GitHub issue with a clear title, detailed reproduction steps, environment details, and minimal test data.**

Reporting bugs effectively helps the opengeos/GeoLibre maintainers reproduce issues quickly and prioritize fixes. The project provides explicit guidelines in its contribution documentation to ensure every report contains the information needed for efficient triage. This guide walks through the exact workflow specified in [[`docs/contributing.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md)](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md), including a ready-to-use markdown template.

## Steps to Report a Bug in GeoLibre

### Open a GitHub Issue

Navigate to the [GeoLibre issues page](https://github.com/opengeos/GeoLibre/issues) and click **New issue**. This is the primary channel for all bug reports and feature requests according to the project documentation.

### Provide a Clear Title

Summarize the symptom in one concise sentence. A strong title immediately communicates the problem to maintainers scanning the issue list.

**Good examples:**

- "Desktop build crashes when loading MBTiles file with custom projection"
- "Web build fails to render vector tiles at zoom level 14+"

### Include Reproduction Steps

List the exact actions that trigger the bug. Structure this as:

- **Steps to reproduce** — numbered sequence of clicks/inputs
- **Expected outcome** — what should happen
- **Actual result** — what actually happened, including error messages

The [[`docs/contributing.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md)](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md) file explicitly states: *"Include steps to reproduce, what you expected, and what happened, plus your OS and whether you hit it in the web or desktop build."*

### Identify Your Environment

Specify:

- **GeoLibre version** — run `npm run version` or check **Help → About**
- **Build type** — **web** or **desktop** (Tauri)
- **Operating system** and version
- **Node.js** and **Rust** versions (for desktop builds)

This distinction matters because GeoLibre maintains separate codepaths for web and desktop architectures, as detailed in [[`docs/architecture.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md)](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md).

### Attach Minimal Test Data

If the bug involves a dataset, provide a small example file (≤ 5 MB) via a public URL rather than uploading directly to the issue. The project hosts sample data in the `geolibre-assets` repository for this purpose.

### Apply the Bug Label

Use the **"bug"** label when creating the issue. The GitHub UI will suggest this label, and it enables triage bots to route your report to the appropriate maintainers automatically.

## GeoLibre Bug Report Template

Copy and paste this markdown template into your issue, then adjust placeholders to match your situation:

```markdown

### Description

A short summary of the bug.

### Steps to Reproduce

1. Open the **Desktop** app (version X.Y.Z) on **Windows 11**.
2. Click **File → Open…** and select `sample.mbtiles`.
3. Observe the crash/error message.

### Expected Result

The MBTiles layer loads and displays correctly on the map.

### Actual Result

The app crashes with the following error: `Error: Invalid MBTiles header`.

### Environment

- **GeoLibre version:** X.Y.Z (run `npm run version` or check *Help → About*)
- **Build:** Desktop (Tauri)
- **OS:** Windows 11 22H2
- **Node:** 22.x, **Rust:** 1.78

### Sample Data

[Download sample MBTiles (≈ 2 MB)](https://assets.geolibre.app/data/sample.mbtiles)

### Additional Context

Any logs, screenshots, or console output that might help.

```

GitHub renders this structure cleanly, making it easy for maintainers to parse critical information at a glance.

## Key Files for Bug Reporters

Understanding these files helps you write more precise bug reports:

| File | Relevance |
|------|-----------|
| [[`docs/contributing.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md)](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md) | Contains the canonical bug-reporting workflow and required information |
| [[`README.md`](https://github.com/opengeos/GeoLibre/blob/main/README.md)](https://github.com/opengeos/GeoLibre/blob/main/README.md) | Links to the issue tracker and community contribution guidelines |
| [[`docs/architecture.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md)](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md) | Explains web vs. desktop build differences to help you specify the affected component |

## What Happens After Submission

After clicking **Submit**, maintainers will:

1. Triage the issue using the **bug** label routing
2. Comment with follow-up questions if reproduction details are unclear
3. Link to a draft pull request when a fix is in progress

Clear, complete reports reduce back-and-forth and accelerate resolution timelines.

## Summary

- **GeoLibre bug reports** are submitted via GitHub Issues at `opengeos/GeoLibre`
- **Required elements**: clear title, reproduction steps, expected vs. actual results, environment details (web/desktop, OS, version), and minimal test data
- **Use the provided markdown template** for consistent, scannable reports
- **Reference** [[`docs/contributing.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md)](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md) and [[`docs/architecture.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md)](https://github.com/opengeos/GeoLibre/blob/main/docs/architecture.md) to understand project conventions

## Frequently Asked Questions

### Where do I submit a GeoLibre bug report?

Submit all bug reports to the [GitHub Issues page](https://github.com/opengeos/GeoLibre/issues) in the opengeos/GeoLibre repository. The project does not use external bug trackers or email lists—GitHub Issues is the centralized coordination point for all bug tracking and feature requests.

### What information is mandatory in a GeoLibre bug report?

You must include steps to reproduce, expected behavior, actual behavior, your operating system, and whether the bug occurs in the web or desktop build. The [[`docs/contributing.md`](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md)](https://github.com/opengeos/GeoLibre/blob/main/docs/contributing.md) file explicitly lists these as required elements for all issue submissions.

### How do I find my GeoLibre version?

Run `npm run version` in your terminal, or open **Help → About** in the desktop application. For web builds, check the version displayed in the application footer or browser console. Include this version number in every bug report to help maintainers identify regression ranges.

### Can I upload large datasets to a GeoLibre bug report?

No—avoid uploading files directly to GitHub issues. Instead, provide a public URL to sample data under 5 MB, such as files hosted in the `geolibre-assets` repository or temporary file-sharing services. This keeps the issue tracker lightweight while still giving maintainers access to reproduction materials.