What this usually means
At its core, this error means the Go compiler cannot prove that the concrete type you provided satisfies the interface constraint you defined. The most common hidden cause is that your constraint interface includes methods that are defined on pointer receivers but you're passing a value type (or vice versa). Another frequent culprit is using a type element (like `~int`) incorrectly—Go 1.18+ constraints are strict about underlying types, not just named types. A third trap is that your constraint embeds another interface that has unexported methods or uses a type set that doesn't include the concrete type's underlying type. The error message points to the exact line but often leaves you guessing which method or type element is missing.
The first ten minutes — establish facts before touching code.
- 1Run `go build -v ./...` and capture the full error message; it usually includes the missing method name or type.
- 2Check the constraint definition: is it an interface with method signatures or a type set (e.g., `~int`)?
- 3Verify method receiver types: if your constraint defines `Foo()`, but your type implements `Foo()` on `*T`, then `T` does not satisfy—only `*T` does.
- 4Use `go tool compile -S` or `go run -x` to see the exact type checking context? No—just inspect the constraint's method set by temporarily removing the constraint and running `go run` to see what methods are available.
- 5If the constraint uses type elements (`~`), ensure the concrete type's underlying type matches: `type MyInt int` satisfies `~int`, but `type MyStruct struct{}` does not.
- 6Check for embedded interfaces: `go doc` the constraint to see the full method set including inherited ones.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchThe constraint interface definition in your code (e.g., `type Constraint interface { ... }`)
- searchThe concrete type's method definitions—are they on `T` or `*T`?
- searchAny embedded interfaces; run `go doc` on the constraint to see flattened methods.
- searchThe call site where you instantiate the generic function/type—check the type argument.
- searchIf using type elements, the underlying type of the concrete type (e.g., `reflect.TypeOf(x).Kind()`).
- searchGo version: `go version` — constraints behave differently before 1.18 (obviously) and there were bug fixes in 1.19+.
Practical causes, not theory. These are the things you will actually find.
- warningMethod defined on pointer receiver but value type passed (or vice versa).
- warningConstraint uses `~T` but concrete type's underlying type doesn't match (e.g., `type MyMap map[string]int` vs `~map[string]int` is fine, but `type MyStruct struct{}` vs `~map[string]int` fails).
- warningConstraint embeds an interface with a method that has a different signature (e.g., different parameter types).
- warningConstraint includes an unexported method from an embedded interface that the concrete type cannot implement.
- warningType parameter is used in a context that requires additional constraints (e.g., `map[K]V` where `K` must be comparable, but constraint doesn't include `comparable`).
- warningUsing a pre-1.18 interface as a constraint that has methods with non-interface parameters (Go 1.18 disallows this).
Concrete fix directions. Pick the one that matches your root cause.
- buildChange the type argument to a pointer: `*MyType` if methods are on pointer receiver.
- buildAdd pointer receiver methods to the value type: implement the interface on `T` instead of `*T`.
- buildModify the constraint to use `~` if you intend to accept types with the same underlying type.
- buildAdd missing methods to the concrete type (check receiver type!).
- buildIf constraint needs `comparable`, add `comparable` to the constraint interface.
- buildIf embedding a third-party interface, copy its method signatures explicitly to avoid unexported methods.
A fix you cannot prove is a guess. Close the loop.
- verifiedRun `go build ./...` and confirm zero errors.
- verifiedWrite a unit test that exercises the generic function with the previously failing concrete type.
- verifiedUse `go vet` to check for interface issues.
- verifiedIf possible, run `go run golang.org/x/tools/cmd/stringer` or similar to generate method stubs? No—simply run the test with `-count=1` to avoid cache.
- verifiedCheck that the concrete type now implements the constraint: `var _ Constraint = MyType{}` compiles? That's a compile-time check.
Things that make this bug worse or harder to find.
- warningAdding a dummy method with empty body to satisfy the constraint—that changes behavior.
- warningUsing `interface{}` as a constraint instead of defining proper interfaces (defeats generics purpose).
- warningPanicking and casting to `interface{}` then type-switching—that's a code smell.
- warningAssuming that because a type has a method, it satisfies any interface with that method—check receiver.
- warningCopying constraints from Stack Overflow without understanding the method set.
Microservice panic on startup after generics refactor
Timeline
- 09:15Deploy new version with generic cache layer using constraint `Cacheable`.
- 09:17PagerDuty alert: service crashing on startup with panic: runtime error: invalid memory address or nil pointer dereference.
- 09:20Check logs: the panic occurs in `NewCache[Order]()` because `Order` does not satisfy `Cacheable`.
- 09:25Run `go build` locally: error 'Order does not satisfy Cacheable (missing method Key)' even though `Order` has `Key() string`.
- 09:30Inspect `Key()` definition: it's on `*Order`, not `Order`.
- 09:35Fix: change `NewCache[Order]()` to `NewCache[*Order]()`.
- 09:40Re-deploy: service starts successfully.
- 09:45Add compile-time check `var _ Cacheable = (*Order)(nil)` to prevent recurrence.
We were migrating our order processing service to Go 1.19 and decided to introduce a generic cache layer to reduce boilerplate. I defined a `Cacheable` interface with `Key() string`, and a `NewCache[T Cacheable]()` function. The `Order` struct had a `Key()` method defined with a pointer receiver because we needed to modify the order during key generation (bad practice, I know). When I wrote `NewCache[Order]()`, the compiler complained 'Order does not satisfy Cacheable (missing method Key)'. I didn't read the full error and assumed it was a bug in the compiler—Go 1.19 had some issues—so I added a workaround by implementing `Key()` on the value receiver as well, but that conflicted with the pointer method.
After the deployment, the service started crashing with nil pointer dereference because the cache was initialized with a nil pointer (the workaround was incorrect). I spent 20 minutes debugging the runtime panic before noticing the compile error was still there. I reverted, looked at the error message carefully, and saw 'missing method Key' even though `Order` had `Key()`. That's when I realized the receiver mismatch. I changed the type argument to `*Order` and everything compiled. The lesson: always read the full error message and check receiver types first.
Since then, I always add a compile-time interface satisfaction check using `var _ Interface = (*Type)(nil)` for pointer receivers, and `var _ Interface = Type{}` for value receivers. This catches mismatches at compile time. Also, I avoid pointer receiver methods unless mutation is absolutely necessary, especially for types that will be used as type arguments in generics.
Root cause
The `Key()` method was defined on `*Order` (pointer receiver) but the generic function was instantiated with `Order` (value type). The compiler requires the exact type to satisfy the constraint; a value type does not automatically satisfy an interface with pointer receiver methods.
The fix
Change the type argument to `*Order` in `NewCache[*Order]()`, or implement `Key()` on the value receiver if mutation is not needed.
The lesson
Always implement interface methods on the same receiver type that will be used as the type argument. Add compile-time checks to catch mismatches early.
In Go, a value type `T` has a method set that includes all methods with receiver `T`, but NOT methods with receiver `*T`. Conversely, `*T` has a method set that includes both `T` and `*T` methods. This asymmetry is a common source of constraint satisfaction errors. For example, if your constraint defines `func (T) Foo()`, then `T` satisfies it only if `Foo` is defined on `T` (value receiver). If `Foo` is defined on `*T`, then only `*T` satisfies the constraint.
When you see 'missing method' but you're sure the method exists, check the receiver. The error message from Go 1.18+ is explicit: it will say 'missing method Foo' and also show the receiver type mismatch if you look at the full output. Use `go build -v` to see the full error.
Go 1.18 introduced type elements in constraint interfaces, like `~int` to mean 'any type whose underlying type is int'. A common mistake is to use `int` (without tilde) and wonder why `type MyInt int` doesn't satisfy. Without `~`, the constraint only accepts the exact named type `int`. With `~`, it accepts any type with underlying type int. However, `~` does not work with type parameters themselves—only concrete types.
Also, note that `~` cannot be used with interfaces that have methods. The Go spec says a type set can contain either methods OR type elements, not both (except for the `interface{}` case). If you mix them, you'll get a compile error.
When you embed an interface in a constraint, all its methods become part of the constraint. If the embedded interface has unexported methods, they cannot be implemented by types outside the package, making the constraint unsatisfiable. This is a Go design decision: unexported methods are package-private. If you embed `fmt.Stringer`, that's fine because `String()` is exported. But if you embed a package-internal interface with an unexported method, your constraint becomes unusable outside that package.
To debug, use `go doc -all` on your constraint to see the full method set. If you see a lowercase method, that's a red flag. Either remove the embedding or copy the exported methods manually.
Go generics require that type parameters used as map keys satisfy the `comparable` constraint. If your constraint doesn't include `comparable`, you can't use that type parameter as a map key. The error message will say something like 'X does not satisfy comparable'. The fix is to add `comparable` to your constraint interface, but be aware that `comparable` is an interface defined in the predeclared identifier `comparable` and cannot be used with other type elements in the same interface. You can embed it: `type MyConstraint interface { comparable; OtherMethod() }`.
Before Go 1.18, interfaces could only define methods, not type sets. Using a pre-1.18 interface as a constraint works, but there's a catch: if the interface has a method that takes or returns a parameter of a non-interface type that is itself a type parameter, the constraint may not work as expected. Also, pre-1.18 interfaces that have methods with empty interface parameters are fine, but if they have methods with concrete types like `int`, they are restrictive. Best practice is to define new constraint interfaces specifically for generics, not reuse old ones.
Frequently asked questions
Why does Go say 'X does not satisfy Y' even though X has all the methods of Y?
The most common reason is method receiver mismatch. If Y defines `Foo()` and X implements `Foo()` on a pointer receiver (`*X`), then only `*X` satisfies Y. Check receiver types. Another possibility is that Y has an unexported method from an embedded interface that X cannot implement.
Can I use `interface{}` as a constraint to avoid these errors?
Yes, but then you lose type safety and generics become useless. You'll have to type-assert inside the function, which defeats the purpose. Always define proper constraints.
How do I check if a type satisfies a constraint at compile time?
Add a compile-time assertion like `var _ Constraint = MyType{}` (for value receivers) or `var _ Constraint = (*MyType)(nil)` (for pointer receivers). This will fail to compile if MyType does not satisfy Constraint.
What does the tilde `~` mean in a constraint?
`~T` means 'any type whose underlying type is T'. For example, `~int` accepts `int`, `type MyInt int`, etc. Without tilde, only the exact type `int` is accepted. Use tilde when you want to accept types based on their underlying structure.
Why does adding `comparable` to my constraint break it?
You cannot mix type elements (like `~int`) with `comparable` directly in the same interface because Go restricts interfaces to either methods OR type elements. Instead, embed `comparable` inside your constraint: `type MyConstraint interface { comparable; Foo() }`.