Understanding Dialyzer error: The pattern can never match the type

I’m using Dialyzer to check over some code that uses the mongodb package. I’ve got a function that abstracts the Mongo.insert_one/4 function and adds in some extra logging for certain conditions:

  def insert(collection, args) do
    case Mongo.insert_one(mongo_pid(), collection, args) do
      {:ok, %Mongo.InsertOneResult{acknowledged: true, inserted_id: id}} ->
        {:ok, %{"_id" => id}}

      # Check for 11000 error (usually this means a duplicate)
      {:error, %Mongo.WriteError{write_errors: [%{"code" => 11_000} | _]} = err} -> {:error, "Duplicate entry"}

      {:error, err} -> {:error, err}
    end
  end

When I run dialyzer, I get the following error:

The pattern can never match the type.

Pattern:
{:error, _err = %Mongo.WriteError{:write_errors => [%{<<99, 111, 100, 101>> => 11000} | _]}}

Type:

  :ok
  | {:error,
     %Mongo.Error{
       :__exception__ => _,
       :code => number(),
       :host => binary(),
       :message => binary()
     }}
  | {:ok,
     %Mongo.InsertOneResult{
       :acknowledged => false,
       :inserted_id => nil | %BSON.ObjectId{:value => <<_::96>>}
     }}

After looking at the mongodb source code I can see that it appears to miss a viable return type:

@type result(t) :: :ok | {:ok, t} | {:error, Mongo.Error.t()}

should be (I think) something like:

@type result(t) :: :ok | {:ok, t} | {:error, Mongo.Error.t()} | {:error, Mongo.WriteError.t()}

My questions are:

  1. Am I correct in thinking that the dialyzer error in my app is resulting from what appears to be an incorrect type definition in a dependency (mongodb in this case)?
  2. Apart from filing an issue, what are the ways to configure dialyzer to ignore that particular error in that specific place?
  3. Why doesn’t Dialyzer catch this problem in mongodb? I cloned the repo, I fired up Dialyzer, and it shows no errors. Is that expected? Common?
  1. It does seem like the function spec for insert_one does not contain {:error, %Mongo.WriteError{}} in the return type. Whether their result type should be updated or not, I’m not sure. Notice that I wrote {:error, %Mongo.WriteError{}} and not {:error, Mongo.WriteError.t()} - I checked and there is no @type t defined in that module so it does not mean anything. This module got introduced in this commit and specs were not updated.
  2. It depends on how you’re running dialyzer. If you run the standalone dialyzer executable, you can use the @dialyzer module attribute. If you use dialyxir, their README.md lists a few more ways to ignore warnings. To me, the ignore file with string matches seems to be the most commonly used way to do that.
  3. Dialyzer accepts flags which configure what kinds of errors are shown. This kind of error would be shown if you used the -Woverspecs option. It is opt-in because it can introduce a lot of noise. Dialyzer has its limits and does not know how to deal with very complex types so it may sometimes “round up” some types to more general ones. I think Elixir’s with may be sometimes confusing it as well? I’m not sure. Adding specs to private functions used may help it. But overall, Dialyzer doesn’t guarantee to find all problems in your code.