Should Elixir get a new "bad return" exception?

Hello,

When writing libraries it is often useful to define behaviours for library users to implement.
In general, those behaviour callbacks must return a specific type, like {:reply, term, term} or {:ok, term}.

Callbacks should be properly documented and then user-implemented, so it is generally fine to exit or raise if the return value does not adhere to the spec.

In Erlang, this is done by throwing an error with {:bad_return_value, retval}. For instance:

defmodule GS do
  def init(_), do: :foo
end

GenServer.start_link(GS, [])

In that case the error will be formatted as bad return value: :foo by the Elixir Exception module, but it does not tell what did not behave properly.

This is a general problem not related to processes. In libraries you can find code like this:

case user_mod.some_callback("hello") do
  {:ok, v} -> {:ok, do_stuff(v)}
  {:error, _} = err -> err
  other -> exit({:bad_return_value, other})
end

I use this pattern a lot. But the stacktrace will not contain user_mod.some_callback, which is a problem.

You can find occurences in OTP code where the bad return tuple includes the MFA that misbehaved, and it is formatted as MyApp.Application.start(:normal, []) returned a bad value: :foo though I cannot find where this is formatted (currently testing on OTP 27.3.

Erlang processes have some kind of helpful output:

-module(foo).
-export([init/1]).
init([]) -> foo.

Calling that module:

gen_server:start_link(foo, [], []).

Gives the “initial call” information in the crash report:

=CRASH REPORT==== 19-Nov-2025::09:32:46.515514 ===
  crasher:
    initial call: foo:init/1
    pid: <0.96.0>
    registered_name: []
    exception exit: {bad_return_value,foo}
      in function  gen_server:init_it/6 (gen_server.erl, line 2222)

This is for processes but I’m not sure anything standard exists for generic functional code.

How do you handle this case in your libraries or behaviours that you expect your coworkers to implement correctly?

Do you think that a ReturnError exception could be helpful ? (not fan of the name but if follows the pattern of ArgumentError).

So we could use it like that:

case user_mod.some_callback("hello") do
  {:ok, v} -> {:ok, do_stuff(v)}
  {:error, _} = err -> err
  other -> raise ReturnError, module: user_mod, function: :some_callback, value: other
end

And/Or what do you think of a special case in the exception module that would treat {:bad_return_value, {{m,f,a}, term} when is_atom(m) and is_atom(f) and is_list(a) in a special way? (Not sure if backwards compatible though).

Thank you