By default dialyzer’s success typing is pretty loose and is happy as long as one branch is OK, here is a minimal example:

  # no error
  @spec foo(:int) :: integer()
  @spec foo(:str) :: binary()
  def foo(:int), do: 123
  def foo(:str), do: nil  # should be a binary!

But after adding the following flags to your mix.exs (this is the config I personally recommend and use):

 dialyzer: [flags: [:missing_return, :extra_return]]

Dialyzer is now able to catch these errors:

lib/repro.ex:19:extra_range
The type specification has too many types for the function.

Function:
Repro.foo/1

Extra type:
binary()

Success typing:
nil | 123

________________________________________________________________________________
lib/repro.ex:19:missing_range
The type specification is missing types returned by function.

Function:
Repro.foo/1

Type specification return types:
binary() | integer()

Missing from spec:
nil

That being said, even if dialyzer is able to understand this particular error with the right flags, it is important to keep in mind that it remains quite limited and that there are a whole range of type errors it won’t be able to catch.

Indeed this seems like a bug or limitation in dialyzer, despite the [:missing_return, :extra_return] flags.

It seems it avoids “diving in” when containers superficially seem to have the correct type:

  @spec bar(:a | :b) :: {:ok, integer()}
  def bar(:a), do: {:ok, 1}
  def bar(:b), do: {:ok, ""}

No warning on {:ok, ""}, but it would catch it if it is the wrong atom {:error, 2} or wrong tuple size {:ok, 1, 2}.

For maps, it seems it is fine as long as the other close returns a map:

  @spec foo(:a | :b) :: %{foo: %{bar: integer()}}
  def foo(:a), do: %{foo: %{bar: 1}}
  def foo(:b), do: %{baz: "whatever"}

but fails when the top-level is not a map.

Will open up an issue to OTP.

Update from the issue:

This is a known limitation, extra_return and missing_return are best-effort and won’t catch much. :-/