Haskell World logo Haskell WorldWrite code, build worlds
Open Source

How to Write a Haskell Bug Report Maintainers Can Fix

You hit a crash in a Haskell library, open the issue tracker, and type three lines about what broke. A week later the issue has one reply asking for your GHC version, and nothing else happens.

A laptop on a wooden desk showing an issue tracker form next to a short Haskell source file open in a terminal window

You hit a crash in a Haskell library, open the issue tracker, and type three lines about what broke. A week later the issue has one reply asking for your GHC version, and nothing else happens. A good Haskell bug report is the difference between that silence and a fix landing in the next release, and it takes about 20 minutes to write properly.

I have triaged issues on several Hackage packages for years. Most stalled reports fail for the same few reasons, and the reporter can fix nearly all of them.

What a maintainer needs from a Haskell bug report

A maintainer reading your issue is trying to answer one question: can I see this break on my own machine in under five minutes? Everything in the report should serve that goal. If they cannot reproduce it, the issue joins forty others in the backlog.

That means four things matter more than anything else:

  • Exact versions. The library version, the GHC version, and the build tool with its version. "Latest" is not a version. Paste the GHC version number and the resolved package version from your freeze or lock file.
  • A minimal reproduction. The smallest program that still shows the bug, ideally under 30 lines, with no dependencies beyond base and the library itself.
  • Expected versus actual behaviour. One sentence each. "I expected decode to return Left with a parse error. It returned Right with an empty record."
  • The full error output. Not a paraphrase, not the last line. The whole thing, including the call stack if you built with profiling.

Operating system and architecture belong in the report too, especially for anything touching the FFI, file paths, or text encoding. A surprising number of "the parser is broken" reports turn out to be a Windows console using code page 1252 instead of UTF-8.

Building a minimal reproduction step by step

This is the part people skip, and it is the part that decides whether your issue gets fixed. Here is the process I follow.

  1. Copy the failing code into a fresh directory. Start a new project with cabal init or stack new so nothing from your application leaks in.
  2. Pin the versions. Write the exact library version into the dependency bounds, for example aeson ==2.2.3.0, so the maintainer resolves the same build plan you did.
  3. Delete until it stops failing. Remove one function, one field, one import at a time. Rebuild after each removal. When the bug disappears, put the last piece back. That piece is usually the trigger.
  4. Replace your domain types. Your Invoice record with 14 fields can almost always become a record with two fields named a and b.
  5. Run it once more from a clean build. Delete dist-newstyle or .stack-work and rebuild. If it still fails, you have a reproduction. If not, you have found an environment issue, which is useful too.

On a recent report against a JSON library, this process took a 400 line module down to 11 lines. The maintainer replied within a day with a fix, because the 11 lines made the bug obvious: a FromJSON instance generated with a non default field modifier was dropping optional fields that contained null.

When you cannot shrink it

Some bugs only appear under load, with a particular database, or after hours of running. In that case, say so plainly and give the maintainer what you can: the conditions under which it happens, how often (once per 10,000 requests is very different from once per day), and any logs with timestamps. Offer to run a patched build.

Search before you file, but do it properly

Every contributing guide says to search existing issues first. The advice is right, but the way most people search is not. Searching for the exact error message often fails because GHC error text changes between compiler versions, and the library may have reworded its own messages.

Search instead for the function name that failed, the type class involved, and the GHC version. Check closed issues too, because the bug may be fixed on the main branch but not released yet. In that case, a short comment asking about a release date beats a new issue.

If you are new to a project, reading its contribution notes first saves time. Our guide to a first open source contribution to a Haskell project covers how to read a repository before engaging with it.

The common advice to always include your whole environment is wrong

A lot of issue templates ask you to paste everything: your full cabal.project, your entire stack.yaml, the full GHC info dump, your list of installed packages.

I disagree with this, at least as a default. A wall of environment output makes the report harder to read, and it hides the one detail that matters among 200 that do not. Maintainers skim. If the GHC version is buried in a 90 line dump, they ask for it again, and you lose several days.

The better approach is to include the four essentials listed above, then add environment details only when they plausibly relate to the bug. A linker error? Include the toolchain details. A wrong result from a pure function? Your installed packages do not matter. If the maintainer wants more, they will ask, and you can answer quickly because you kept the reproduction directory.

The one exception is the build plan. If the bug could be a version conflict between two dependencies, include the relevant lines from your freeze file. Knowing how Stack and Cabal resolve versions differently helps you decide which lines are relevant.

Tone, titles, and what happens after you file

Write the title as a statement of the bug, not a feeling. "decodeStrict accepts trailing garbage after a valid object" is a good title. "Parser totally broken??" is not.

Keep the tone factual. Many Haskell maintainers are volunteers working evenings, and a report that assumes good faith gets a better response.

After filing, watch the issue for a week. If the maintainer asks a question, answer within a day or two if you can. If nothing happens after two weeks, a single polite follow up is reasonable. If the maintainer decides the behaviour is intended, accept it gracefully; our piece on how open source maintainers decide what features to reject explains the reasoning behind many of those calls.

If you have time and the fix looks small, offering a pull request with a failing test case is the strongest follow up there is. Even a test without a fix is valuable.

Frequently asked questions

Should I report a bug if I am not sure it is a bug?

Yes, but say so in the title or first line, for example "Possible bug or documentation gap in withFile". Unclear documentation is a real problem worth fixing, and maintainers would rather hear about confusion than have users quietly work around it. Include the same minimal reproduction either way.

Where do I report a bug in GHC itself rather than a library?

GHC bugs go to the GHC issue tracker on the project's GitLab instance, not to library repositories. If your reproduction fails with only base imported, the bug is likely in the compiler or base. Check whether it still happens on the newest GHC release before filing.

How long should I wait for a maintainer to respond to an issue?

For an actively maintained package, a first response within one to two weeks is typical. Check the commit history first: if the last commit was two years ago, the package may be unmaintained. In that case look for a fork or consider the takeover process on Hackage rather than waiting.

SR
Sonja Reiter

Sonja Reiter contributed to three major open source projects and started writing documentation when she noticed most tooling guides were written by people who had never taught anyone to use them. She covers build tools, package ecosystems, and the invisible quality-of-life differences between development setups.

More posts by Sonja

More in Open Source

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten qvantor rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto