Haskell Typed Holes for Writing Code With GHC's Help
You know roughly what a function should do, you have written the signature, and then you sit there staring at the right-hand side because the types involve three nested constructors and a callback.

You know roughly what a function should do, you have written the signature, and then you sit there staring at the right-hand side because the types involve three nested constructors and a callback. Students in my second-week lab do this constantly. They guess an expression, compile, read a wall of mismatch errors, guess again, and twenty minutes later they have something that typechecks but that they cannot explain.
Haskell typed holes turn that guessing into a conversation. You put an underscore where you are stuck, and GHC tells you exactly what type belongs there, which local variables are in scope with their types, and often a short list of functions that would fit. This article shows how to read that output, how to make it more useful, and where it stops helping.
What a typed hole actually tells you
A typed hole is any expression that starts with an underscore and is not bound to anything. The plain form is a single _. Named holes like _rest or _handler work the same way and make the error messages easier to match back to your code when you have several.
Take a small example. You are writing a function that applies a validation to every field of a form and collects the failures:
validateAll :: [(String, String)] -> (String -> Maybe String) -> [String]
validateAll fields check = _
Compile this with GHC 9.6 or later and you get an error that starts with "Found hole: _ :: [String]", followed by a block titled "Relevant bindings include", listing fields :: [(String, String)], check :: String -> Maybe String and validateAll itself. Below that comes "Valid hole fits include", with candidates such as mempty, [] and sometimes fields-derived suggestions if the types happen to line up.
Those three sections are the whole tool. The hole type tells you the target. The relevant bindings tell you your ingredients. The fits tell you what GHC could find that already matches, without any thought about whether it makes sense.
Filling a hole one layer at a time
The trick that makes holes worth using is never to fill one completely. You replace a hole with a function application that contains new, smaller holes, compile again, and let GHC narrow the types for you.
Continuing the example, you suspect the answer is some kind of map followed by a filter. So you write:
validateAll fields check = _collect (map _perField fields)
Now GHC reports two holes. _perField has type (String, String) -> a0 and _collect has type [a0] -> [String], where a0 is an ambiguous type variable it cannot pin down yet. That ambiguity is information: it says you have not decided what each field turns into. Decide, by writing _perField = \(_, value) -> check value, and the next compile tells you _collect needs type [Maybe String] -> [String]. The fits list for that will usually include catMaybes, provided Data.Maybe is imported.
That is the rhythm: one decision per compile, each one shrinking the unknown. With ghcid running on every save, a round trip takes well under a second on a small module, and the whole function above comes together in four or five saves. In my class logs, students who work this way finish the week-two exercise sheet in about 40 minutes on average; the ones who guess whole expressions take closer to 70.
Making the fits list worth reading
By default GHC shows up to 6 valid hole fits and stops. That default is fine for small types and nearly useless for polymorphic ones, where undefined, mempty and id-shaped things crowd out what you wanted. A handful of flags change this.
| Flag | What it changes | When I turn it on |
|---|---|---|
-fmax-valid-hole-fits=20 | Shows more candidates before cutting off | When the hole type involves a type class |
-fno-max-valid-hole-fits | Removes the limit entirely | Rarely, the output can run to hundreds of lines |
-frefinement-level-hole-fits=1 | Suggests functions that need one more argument, shown with their own holes | When the answer is clearly "some function applied to something" |
-fno-show-type-app-of-hole-fits | Hides the explicit type applications in fit output | Almost always, it cuts visual noise |
-fdefer-typed-holes | Turns hole errors into warnings so the rest of the module still compiles | In GHCi while exploring, never in CI |
Refinement fits are the most useful of these and the least known. With refinement level 1, a hole of type [Maybe String] -> [String] might suggest mapMaybe _, telling you that mapMaybe would work if you supplied one more argument, and showing that argument as a new hole with its own type. Level 2 goes a step further and gets slow on large modules, so I leave it at 1.
You can set these per session in GHCi with :set -frefinement-level-hole-fits=1, which is how I prefer to use them. If you have not built a GHCi habit yet, the guide to GHCi as a daily workflow covers the reload loop that makes this comfortable.
The advice to trust the first fit is wrong
A common tip in forum threads is that when GHC lists a hole fit, you should take it, because the compiler knows the types better than you do. I disagree, and I have watched this advice produce working code that is subtly broken.
The fits list is a search over names whose types unify with the hole. It has no idea what your function is for. For a hole of type [a] -> [a], GHC will happily offer reverse, tail, cycle, init and id. All of them typecheck. Only one of them is what you meant, and tail and init will crash on an empty list at runtime. Last term a student filled a hole with tail because it was listed first, passed every test that used non-empty input, and lost marks when the grader fed it an empty list.
The rule I give instead: use the hole type and relevant bindings as facts, and treat the fits list as a reminder of names you might have forgotten. If a fit surprises you, look it up in GHCi with :doc or :info before you accept it. When a type is so general that a dozen unrelated functions fit, that is usually a sign your signature is too loose, and a newtype or a more specific type would serve you better than any fit.
Holes in types, not only in terms
Underscores also work in type signatures, where they are called partial type signatures. Write helper :: _ -> Int and GHC reports the inferred type for the underscore as an error, or as a warning with PartialTypeSignatures enabled. This is handy when you are refactoring and want GHC to tell you what an argument type turned out to be, then paste it in.
Two cautions. First, a partial signature with the extension turned on will compile silently with only a warning, so it is easy to leave one in a library by accident. Add -Werror=partial-type-signatures to your Cabal file once the code is meant to ship. Second, wildcard constraints like _ => a -> String work, but the inferred constraint set can be larger than you would write by hand, so read it before copying.
When the hole messages themselves still look dense, the walkthrough on reading GHC error messages without panicking breaks down the layout line by line, and the same reading habit applies here.
FAQ
Do typed holes work in GHCi?
Yes. Typing an expression with a hole at the GHCi prompt prints the same report. Combine it with -fdefer-typed-holes and you can load a half-finished module and still test the functions that are complete.
Why does my hole show a type like a0 instead of a real type?
GHC could not infer it yet because nothing around the hole constrains it. Add a type annotation nearby, or fill in the surrounding expression a little more, and the variable usually resolves on the next compile.
Can typed holes slow down compilation?
The fit search can, especially with refinement level 2 or no fit limit in a module with many imports. If a save takes more than a few seconds, drop the refinement level or lower the maximum number of fits.
Is there editor support for holes?
Haskell Language Server shows hole fits as code actions, so you can pick one from a menu. It reads the same GHC output, so the same caution about trusting the first suggestion applies.
More in Programming
Programming
Haskell where vs let and Which One to Reach For
A student sent me a function in the third week of last term that worked out a shipping band from a weight in grams and a...
Programming
Haskell Semigroup and Monoid: When Each One Fits
A student brought me a function last term that merged three configuration records into one.
Programming
Haskell Functor and Applicative Explained With Real Code
You have a value stuck inside a Maybe, a list, or an IO action, and you keep writing case expressions just to apply one small...