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: Stavros Aronis - What does Dialyzer think about me? | Code BEAM STO 19 - YouTube

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.

In case You want to catch something like this, You could do

   case arg do
     1 -> do_ok()
     _other -> do_error()
 end

and give spec to the do_ok, do_error functions, as mentionned in this previous post

The video was helpful. I wish the speaker had continued for another thirty minutes and showed some examples of errors that Dialyzer wouldn’t catch.