Logo

Home About Community Download Documentation Planet



Bugs, Patches & Translations

How to Report a Bug

There might be a chance the bug you want to report is not actually a bug. Please check this list of canned responses before filing a report. If you don't, you might find your issue quickly closed and referenced to one of the items on that list.

Important: If you are encountering a crash, please make sure to provide a stack trace when you file your report. Doing so requires installing "debug symbols" for PulseAudio and its libraries. Documentation for installing debug symbols is usually provided by your distro.

Important: If you are using Ubuntu please read this before filing a bug.

Note: Arch Linux does not have a simple way to install debug symbols, but you can install the pulseaudio-git and libpulse-git packages from heftig's repo, instructions here. Those replace the "official" pulseaudio packages with ones that include the very newest code from upstream, and the packages happen to include the debug symbols in them.

Also, make sure to include the verbose output of PA when this problem happens.

Getting verbose server logs from PulseAudio

In order to capture all the needed debugging info, you must first tell PulseAudio's error log to report verbose (debug-level) data, and have this data written to a temporary logfile which you can then send to the developers:

Step 1: stop the normal background pulseaudio process...

$ systemctl --user stop pulseaudio.service pulseaudio.socket

Step 2: start pulseaudio in a terminal with logs going to /tmp/pulse.log...

$ pulseaudio -vv --log-time 2> /tmp/pulse.log

Step 3: stop pulseaudio with a ctrl-c keypress.

Step 4: start the normal background pulseaudio process...

$ systemctl --user start pulseaudio.service pulseaudio.socket

Optionally, to display debug errors in real-time, you may run tail -f /tmp/pulse.log in a second terminal window once you have completed the steps above. This can be useful for discerning exactly when bugs occur.

Running PulseAudio manually

First, you might need to stop your existing daemon. If your system uses systemd to manage user sessions, stop the session:

$ systemctl --user stop pulseaudio.{socket,service}

If you're not using systemd, you might need to stop a running PA first by issuing pulseaudio -k

If autospawning is enabled (which it is by default when not using systemd) you might have to race against it when restarting PA, so it might be a good idea to issue pulseaudio -k ; pulseaudio -vv in a single command and try a few times. Usually that should work well enough to win the race. If it doesn't, adding autospawn=no to ~/.config/pulse/client.conf will disable autospawning. Removing that line (or that file) will restore your default autospawn behaviour.

Now, you can run pulseaudio -vv in a terminal and try to reproduce your issue.

Below is a rough outline of how a stack trace can be acquired with gdb:

$ LD_BIND_NOW=1 gdb pulseaudio
>> run -vv
>> ...
>> *** crash ***
>> thread apply all bt full
>> ...
>> *** etc. etc. ***

Before posting a bug report you might want to check this list of broken ALSA sound drivers. (might be out of date)

If you have an issue with PulseAudio's mixer handling, read this first. If you have an issue with memory consumption read this first. If you feel that that PA doesn't honour your default device choices, read this first. Other canned responses ?you find in this list.

Patches are preferably submitted as a Gitlab Merge Request (this is equivalent to Pull Requests on Github, if you are familiar with those. If not, refer to the Gitlab documentation. Before submitting patches please read through our coding style guidelines.


Patch Review Status

We track the submitted patches here. That page is updated every two weeks. If you have submitted a patch, and you're waiting for someone to review it, it should be listed on that page (within two weeks). If it's not, then we have missed your patch, in which case please contact the maintainers (for example by sending a mail to the mailing list).


Translations

Translations should be submitted via Fedora's Weblate (we're not otherwise affiliated with Fedora, but they offered to host the translation service for us).