Reporting Bugs#

There are three types of bugs:

  • wrong or unexpected behavior that don't cause errors

  • soft errors

  • hard errors (crashes)

Incorrect Behavior#

In this case, please report the issue on our issue tracker with enough details to help us reproduce the problem.

You should include the following details:

  • a screenshot/screencast showing the problem

  • a description of the problem

  • steps to reproduce the problem

  • OS and Zrythm version information

  • last 100 lines of the log file

The following subsections explain how to provide this information.

Obtaining a Screenshot/Screencast#

You can press the PrintScreen on your keyboard to obtain a screenshot.

To obtain a screencast you can use a screen recording software such as OBS, or Control-Shift-Alt-R on GNOME.

Problem Description#

You should include as many details as possible to help us understand and reproduce the problem, otherwise we can't do anything about it. Here is an example of a good bug description:

Pixelated and misaligned timebase master and transport client icons

As can be seen in the following screenshot, the two icons are seemingly misaligned, moved into each other and also very pixelated.

Steps to Reproduce#

Please give the exact steps to reproduce the issue, starting from a blank project (if possible). We will follow these exact steps to reproduce the error so that we can fix it. If we can't reproduce the issue, it is very difficult to find or fix the issue.

Here is an example of helpful steps to reproduce:

  1. Create an empty project

  2. Add a MIDI track

  3. Create a region starting at bar 1 and ending at bar 5

  4. Add a note inside the region starting at bar 2 and ending at bar 4

  5. Split the note at bar 3

  6. Delete the 2nd note

  7. Zrythm freezes

OS and Zrythm Version Information#

You can copy the Zrythm version from the About dialog or (preferred) use the --version option when launching Zrythm in a terminal.

../_images/terminal-version-info.png

You can obtain OS information from the About dialog (click Troubleshooting then Debugging Information)

../_images/debugging-info.png

Log#

The log file can be found in the location specified here. Please provide at least the last 100 lines. You may be asked to provide the full log file (please compress it first).

How to Report an Issue on GitLab#

Note

You must first register an account with us (if you don't already have one). You will be asked to login (or create an account) when you try to create an issue.

First, go to our issue tracker. You will see the following page.

../_images/gitlab-issues.png

List of Zrythm issues#

Click on New Issue. You will see the following page where you can fill in details about the issue you are facing. Click on Choose a template... under Description and select what best describes your issue (e.g., a bug).

../_images/gitlab-new-issue-selecting-template.png

Selecting an issue template#

Then, enter the required details to help us understand, reproduce and fix the issue.

../_images/gitlab-filling-in-new-issue.png

Filling in details according to the template#

When you are done, click the Create Issue button to submit the issue to us.

../_images/gitlab-clicking-create-issue.png

Submitting an issue#

Existing Issues#

Please make sure to first search our issue tracker for any similar issues before making a new one (having multiple tickets about the same issue wastes our time).

If you find the issue you are having in an existing ticket, please read it and comment on it with additional information, if you have any. If you have nothing to add but want us to fix the issue faster, you may add a reaction (like a thumbs up) to let us know it's important.

If you are not sure if your issue is a duplicate, please submit it anyway.

Tip

We generally work on issues we consider high-priority first, however if you want something fixed quickly and are willing to pay feel free to contact us with your proposal.

Soft Errors#

In this case Zrythm will display a bug report dialog. Please follow the instructions in this dialog to report the issue.

Crashes#

If Zrythm crashed, then a bug report dialog may not be shown or the log file may not contain enough information to help us fix the issue. In this case, please follow the steps below to generate a core dump or a backtrace.

Generating Core Dumps on GNU/Linux#

You will need to type some commands into a terminal. Also, please make sure you have systemd-coredump or the equivalent package installed on your distro.

Note

The following steps apply to systemd users (the vast majority of GNU/Linux users). For non-systemd users, you can usually obtain the core file in the current directory after running the first 2 commands below and running Zrythm until it crashes.

First, enable core dumps:

ulimit -c unlimited

Tell Linux to add the PID (Process ID) to the core dump:

sudo sysctl -w kernel.core_uses_pid=1

Run Zrythm and make it crash. An intermediate core dump file should now be generated in /var/lib/systemd/coredump. Use coredumpctl to verify:

coredumpctl list -1

You should see something like the following:

TIME                          PID  UID  GID SIG    COREFILE EXE
Thu 2023-08-24 05:48:14 CDT 23179 1000 1000 SIGILL present  /opt/zrythm-1.0.0.beta.4.12.1/bin/zrythm

Note that under COREFILE it says present, so a core file exists.

Now we can finally export the core dump file to a location of our choice (in this case in my Downloads directory) by passing the PID to coredumpctl:

coredumpctl dump 23179 --output=/home/alex/Downloads/core.23179

Important

Change the file path given to --output to your desired location.

Please send us the core dump file (in the example above it can be found at /home/alex/Downloads/core.23179).

See also

Getting a Backtrace on Windows#

Open the Command Prompt app as an administrator by searching for cmd in the start menu, then right clicking on the app and selecting Run as Administrator. Then, type the following and press enter/return:

"C:\Program Files\Zrythm\bin\drmingw.exe" -i"
../_images/drmingw-install.png

This will install DrMingw as the default debugger (you can uninstall it afterwards).

../_images/drmingw-install-confirmation.png

Then, run C:Program FilesZrythmbinzrythm_debug_gdb.exe and make it crash. When Zrythm crashes, you will see a Dr. Mingw window appear on the screen with error details.

../_images/drmingw-trace.png

Click File -> Save As... and save the error file somewhere. Please send us this error file.

../_images/drmingw-saveas.png

When you are done, if you wish, you may uninstall Dr. Mingw with the following command:

"C:\Program Files\Zrythm\bin\drmingw.exe" -u"
../_images/drmingw-uninstall.png

A confirmation dialog will appear:

../_images/drmingw-uninstall-confirmation.png