If I recall correctly this video did help me a lot. It helps you think like Dialyzer which makes it easier to understand why it (does not) reports an error: https://youtu.be/Nxsw1jRE2A4

While it in some parts is a bit heavy to read, the original paper on success typing contains a lot of information and if you understand what success typing is (and what it is not), then deciphering the error messages becomes easier.

Dialyzer is never wrong. When it knows an spec mismatch will happen in any case, it will report an error. If it might happen, it won’t as the conditions in which the function returns a non matching type might never occur. After all: you as a developer might call the function only in a way that makes it matching.

Example

@ spec foo(arg :: integer) :: :ok
def foo(arg) when is_integer(arg) do
   case arg do
     1 -> :ok
     _other -> :error
 end
end

You might think Dialyzer should/would warn that :error is not in the spec.

However, Dialyzer thinks different:

Maybe this function is only ever called with foo(1); then there is no issues at all as indeed it only will return :ok. I will not raise an issue.

There are flags to tune this behavior but their usage might cause other ‘issues’ so those are false by default.