Bug reports

If you've found a bug

The by far fastest way to handle a bug is of course to fix it and submit a patch. Even a patch that is rudimentary but points out where the faulty code is is better than no patch at all.

The better the problem is isolated and the smaller the test program (or test case) that shows the bug is, the faster it can be fixed. If at all possible, try to write a small program that provokes the bug.

When you have a sufficiently small program or example that shows the bug, please create an issue on GitHub to report the bug.

When you submit a pull request on GitHub, mention the issue ID (e.g. #1234) in the post text of the pull request.

Please include the following information:

• OTP version (e.g. OTP-23.2)
• Configure flags when building (e.g. ./configure --enable-shared-zlib)
• Application versions if different than the main distribution
• Any source patches that may be relevant
• Operating system/distribution

A description of the bug and any helpful hints that you can think of are also appreciated.

If the problem seems to be in the virtual machine

A typical example may be a BIF that behaves oddly, or crashes/core dumps, but may of course be other things.

In these cases it may be very hard to create a small program that shows the error, but if that's possible, that's of course appreciated...

If the error seems to be in the VM, also supply information about:

• Any NIF modules (including OTP-supplied modules) that are loaded when the error occurs
• Any dynamically loaded drivers (including OTP-supplied) that are in use when the error occurs
• Any parameters used when starting the VM (e.g. +SDio 1024)
• Hardware configuration (e.g. 4 core Intel i7 with 4 GB of memory)
• If there is a core dump, debug the core and do a backtrace for each thread:

  $ gdb  /usr/local/lib/erlang/erts-5.9.1/bin/beam.smp ./core
  (gdb) info threads
  ...
  (gdb) thread 1
  (gdb) where
  ...
  (gdb) thread 2
  (gdb) where
  ...

• Describe under which circumstances the crash occured as thoroughly as possible
• If there is no core, but the erlang VM crashes, enable coredumps with the ulimit/limit command so that the next time the machine crashes, a core will be created.
• If there is an erl_crash.dump file, try to analyze that with the crashdump_viewer (an erlang module included in OTP) and include at least the slogan in the report

If OTP wants you to create a core when the VM hangs rather than crashes

Sometimes the bug manifests as a hanging process or VM. If OTP needs a core file to analyze the problem, do like this:

• If you can access the VM, call os:getpid() to get the OS pid of the beam process
• Use kill -ABRT to kill the process and dump a core. This only works if the ulimit is set so that cores are dumped, otherwise use gcore instead.
• Use gcore to produce a core without killing the process (might hang it for a long time though, so be prepared for interrupted service)

If OTP wants the whole core file

If you have VM crashes, OTP may ask you for the complete core dump. For OTP to be able to read the core properly, the binaries usually need to be supplied as well (i.e. beam/beam.smp etc).

The best way to supply OTP with the relevant files is to pack the source tree where the OTP that crashed was built, if that is still available and not cleaned. This means the OTP distribution where you've run configure with the exact same parameters as you used when building the erlang VM that crashed and then have run 'make' to build all the binaries. Pack that in a compressed tar file together with the core and OTP will have a much better chance of finding the bug.

If there is an erl_crash.dump file, supply that as well.

The compressed tar file, which is probably quite large, can be delivered to OTP in many ways. Do however not put it on a public webserver without security and post the URL on the list. Core files may contain all sorts of sensitive information you do not want to spread (for security reasons).

You will probably have one single OTP developer to communicate with now, so send any information to her/him directly. Also, it may be a good idea to request a public gpg encryption key to use on any login information you would like to send to the developer.

The core and binaries can be fetched by OTP from either your FTP/Website, from your dropbox (in which case you could share it only to the developer at OTP) or any other service you may have available.