Instance head is not headed by a class [GHC-56538]

Instance declarations specify the operations that place a type into a type class. For example, an instance of Eq describes how (==) works for a type. Instances only make sense for things that are, in fact, type classes - instance Int Int is nonsense, as is instance thing Int.

A head is the thing being applied at the beginning of a chain of applications. For instance, in MonadReader Int MyMonad, the head is MonadReader. When there are no arguments, the head is the entire construct, so Int is the head of Int. For an instance declaration to make sense, the head of the instance being defined must be the name of a type class. The terminology here is a bit overloaded, because the instance being defined is the instance head, and the head of the instance head must be a class.

For example, in:

instance Show Int where
  ...

the instance head is Show Int and its head is Show.

Normally, this error is caught by a different step, where GHC uses the type system to ensure that the instance being defined is of a class. But a lower-case name is a type variable, which the type system cannot rule out.

Examples

Typo: lower-case class name

Error Message

IntInstance.hs:5:10: error: [GHC-56538]
    • Instance head is not headed by a class: someClass Int
    • In the instance declaration for ‘someClass Int’
  |
5 | instance someClass Int where
  |          ^^^^^^^^^^^^^

Explanation

This example shows a typo in which a type class name is written in lower case in an instance declaration. This results in GHC treating it as a type variable, and failing when it is not a concrete class.

IntInstance.hs
Before
module IntInstance where

class SomeClass a where

instance someClass Int where
After
module IntInstance where

class SomeClass a where

instance SomeClass Int where