Sometimes, Sonic Pi may not work properly, or behave in unexpected ways.

What follows is a guide to troubleshooting some of the most common issues that occur, (including some workarounds or possible solutions), and details of the best way to raise an issue if you still end up needing to ask for help or bring something to our attention.

⚠️ Note: We are currently working on the next version of Sonic Pi, to be released soon. There are some differences between the existing and new versions of Sonic Pi that this guide does not currently fully take into account - so if you are having issues with a stable released version of Sonic Pi, it's worth keeping this in mind. If you have any questions about or problems with this guide due to that, feel free to reach out to us in any of the places we gather as a community. We'll be updating this guide when the new release is out.

If you encounter an issue with Sonic Pi, it's always a good idea to try these things first:

1. Make sure you're using the latest version of Sonic Pi.

   ℹ️ You can find the current version in the bottom bar of the UI, or at the top of the GUI log file. See https://sonic-pi.net to find the latest version.

2. Try restarting Sonic Pi and see if that resolves your issue.

3. Try restarting your system and see if that resolves your issue.

If those don't work, then see below for a few more things you can try - including a list of some common issues and suggestions that may help to solve them. Hopefully they'll help you resolve your issue. :)

If you are seeing errors or experiencing unexpected behaviour when trying to use Sonic Pi, its log files may provide clues such as error messages that might indicate possible causes. You can find the log files in one of two ways:

• If you are having an issue with an error when Sonic Pi tries to start up, then if it shows a pop up window with the startup error message, the button labelled 'Show Details...' reveals an error report containing these log file details.
• Otherwise, these can be found usually in your home directory, (or the location set by the SONIC_PI_HOME environment variable) at .sonic-pi/log.

If Sonic Pi has failed to start up, or has behaved unexpectedly in some way, sometimes there are still things that you can do to work around the problem, even if a more permanent solution doesn't yet exist.

If you come across any other issues, and want to help others going through them, then do let us know, and we can update this list. :)

First, a quick bit of background information. When Sonic Pi tries to start up, it tells its sound engine (a piece of software called scsynth) to connect to an audio device, so that it has somewhere to send all of your sounds. (By default, scsynth tries to connect to the audio device that your Operating System is currently using (ie, the current system audio device)). In some situations, when it tries to do this, it's unable to. This may be for a handful of reasons. Sometimes it's because scsynth is trying to talk to the audio device in a way it doesn't support; sometimes scsynth just doesn't know how to talk to the device at all. When this happens, there's usually helpful information in the scsynth.log log file. You might see messages in there similar to this:

SC_PortAudioDriver: PortAudio failed at Pa_OpenStream with error: 'Device unavailable'

could not initialize audio.

Solutions include:

• Changing the way that Sonic Pi/scsynth tries to connect to an audio device. It's possible to tell Sonic Pi/scsynth to try to connect to an audio device using different settings, or even try to connect to a different audio device altogether if you have more than one attached to your system. Here's how:
  • Take a copy of the config file found in the Sonic Pi source code at app/config/user-examples/audio-settings.toml (online at audio-settings.toml) and place it in your .sonic-pi/config folder (found in your user's home folder on your device, or if you use the SONIC_PI_HOME environment variable, wherever that points to).
  • Read through the comments in the file and uncomment lines that have settings that you could change to fit your needs. For example:
    • If the scsynth.log log file mentions something about an error with a sample rate, try uncommenting the line # sound_card_sample_rate = 44100 and change it so that it sets the sample rate to what you need.
    • If the log file error is something about Unanticipated host error, this often means you might need to connect to a different audio device - try uncommenting the line # sound_card_name = "" and changing it so that the name matches part of a different audio device. The scsynth.log file prints out a list of all the audio devices it can find attached to your system, so you can pick another one and use that instead. For example: if the log file says you also have an ASIO device, you can try editing the setting to say sound_card_name = "ASIO".
  • Save your config change, and restart Sonic Pi. Hopefully the change will work!

You may see messages in the logs that say things like port: XXXX [Not Available], or Port unavailable: XXXX. It's possible that parts of Sonic Pi from a previous session did not shut down successfully last time, or some of the ports that Sonic Pi needs are being used by other processes/programs. (Note, this should be less of a problem with recent versions of Sonic Pi that attempt to pick ports that are not already in use. In recent versions of Sonic Pi, only port 4560 is hardcoded). Here are a couple of things you can try to work around this:

1. Check that Sonic Pi or Supercollider aren't already running

2. Try to close other Sonic Pi related processes:

   Note: Be very careful what processes you close, make sure you don’t close any processes that are critical to the system, or processes of another app you're doing some work on.

   If you're on Raspbian/Raspberry Pi OS, macOS or Linux open the System Monitor; or if you're on Windows open the Task Manager (press Win+r, type 'taskmgr', and press enter)...

   and try closing the following processes:

   • beam.smp
   • Erlang
   • Ruby/Ruby Interpreter
   • Sonic Pi
   • Sonic Pi Portable Launcher
   • Supercollider
   • scsynth

3. If that doesn't work, try to find out what processes are using the ports and close those processes (if it's safe to do so):

   Note: Be very careful what processes you close, make sure you don’t close any processes that are critical to the system, or processes of another app you're doing some work on.

   On Raspbian/Raspberry Pi OS, macOS or Linux:

   • To find the processes that are using the ports, open the Terminal and type something like lsof -n -i:XXXX, where XXXX is the port number that the Sonic Pi logs said was unavailable.
   • Check what those processes are (make sure they aren’t important processes that are critical to the system, or processes of another app you're doing work on). Then if it’s safe to do so, you can stop those processes by typing kill [Process ID].

   On Windows:

   • Open the Command Prompt (press Win+r, type 'cmd' and press enter) and typing: netstat -a -b -n -o. This will display a list of some processes with the ports they're using. Look through the list to find any processes that are using the ports that Sonic Pi needs.
   • Check what those processes are (make sure they aren’t important processes that are critical to the system, or processes of another app you're doing work on), then if it’s safe to do so, you can stop those processes from the Task Manager, or via. the Command Prompt by typing taskkill /PID [Process ID].

Sonic Pi keeps its configuration files in a directory named .sonic-pi, usually stored in the current user's home directory. Sometimes, it may not be able to create .sonic-pi because you may not have permission to create or modify things in that location. You can work around this by telling Sonic Pi to store .sonic-pi and its contents somewhere else. You do this by storing the new location in an environment variable, as follows:

On Windows:

• Open the Command Prompt (press Win+r, type 'cmd' and press enter)
• Enter the command setx SONIC_PI_HOME "path/to/folder" (Replace path/to/folder with a folder that your user can make files & folders in)

On macOS, Linux or Raspbian/Raspberry Pi OS:

• Open the terminal
• find out what shell your system is using:
• Enter the following command in the terminal: ps -p $$. This should print out something that looks similar to the following:

  PID TTY           TIME CMD
  1600 ttys000    0:00.39 -zsh

(Where this shows that the shell in use in this example is zsh).

• Add a line to a special script file that will set the SONIC_PI_HOME environment variable for you. (The name of the file will vary depending on which shell you are using - on many systems this file is called .bashrc because the shell that the system is using is called bash. On macOS the script file might be called .zshrc). You can add the necessary line to the file by entering a command in the terminal that is similar to the following: printf "\nSONIC_PI_HOME=\"path/to/folder\"" >> ~/.bashrc. (Replace path/to/folder with a folder that your user can make files & folders in - the double >'s, and the \'s are important!! and replace ~/.bashrc with ~/.zshrc or whatever the equivalent file is for the shell that your system is using).

The version of Sonic Pi (v3.2.2) that is bundled with the Raspberry Pi (and provided in the Raspberry Pi software repository) is a little outdated. If it doesn't work for you, or you wish to try a more up-to-date version, the best way to get Sonic Pi working on your system is:

1. Make sure that you have the most recent version of Raspberry Pi OS loaded on your Pi. (See https://www.raspberrypi.com/documentation/computers/os.html#updating-and-upgrading-raspberry-pi-os for info about updating)
2. Uninstall the built-in Sonic Pi

   sudo apt-get remove sonic-pi

3. Download the latest version from our own website: https://sonic-pi.net
4. Double click on the downloaded file to install it (and enter the Pi user's account password when prompted)
5. Reboot your Raspberry Pi

If your issue still isn't resolved, please create a bug report issue on our GitHub issues page.

On Linux systems, Sonic Pi depends on audio servers such as the Jack Audio Connection Kit or Pipewire to run. If Sonic Pi doesn't start up successfully, your chosen audio server might not have been configured correctly or optimally. If the GUI complains that "The Sonic Pi server could not be started!" or the message "Loading previous buffer contents. Please wait..." does not disappear from your buffers after startup, a common reason is a problem with one of these tools.

In order for JACK to work properly, the jackd audio daemon needs to be started in the background - if it isn't running already, the Sonic Pi server will start it for you. However, if this fails, Sonic Pi never finishes starting up. As a workaround, try this:

• Be sure that you have closed Sonic Pi
• Start jackd manually using the qjackctl GUI
• Once it has started, start sonic-pi again

Some Linux distributions do not automatically allow JACK to start up in real-time mode 'out of the box', which is required. If JACK has failed to start up successfully because of this, then it is necessary to allow real-time mode. Instructions for doing so are on the Linux real-time config FAQ.

On some Linux distributions, (often Arch Linux and its derivatives such as Manjaro and Endeavor OS) when the active audio server is Pipewire, it has been necessary to install some extra software packages to get Sonic Pi working. This usually includes some version of JACK, as well as jack-example-tools.

In some cases, you may find that Sonic Pi starts up but produces no sound when code is run. One common reason for this is that you might have switched sound output devices on your computer while Sonic Pi is running. Currently Sonic Pi is unable to automatically change which sound device it communicates with while it is running. As a workaround, you can choose the desired sound output device, either in your Operating System's sound settings or by setting it via Sonic Pi's audio settings config file, (see the config examples) before launching Sonic Pi.

This may happen if you are asking Sonic Pi to do certain things that your computer is unable to keep up with - for example:

• Playing one or more synths or samples in loops very, very quickly
• Using FX that are complex or resource demanding (for example, :reverb) inside loops that repeat very quickly
• More generally, looping any code in Sonic Pi that does not have much time to complete before the next loop around

Solutions include:

• increasing the time between samples or synths
• allowing more time for FX to complete before the next loop (for example, within an enclosing FX block, increasing the duration that samples and synths play for, or playing more samples or synths in a row (see chapter 6.2 in the tutorial for a handy shortcut)
• enclosing entire live_loops in FX rather than using FX within the loops themselves (note, there is a special consideration in this case: you cannot modify opts of an FX block that wraps an entire thread or live_loop while the code is running).

You may encounter situations where Sonic Pi produces an error, even though the code you attempt to run seems correct. There are a couple of ways this can happen. Examples include:

• Using code in your Sonic Pi composition that is not part of the officially supported list of functions
• Attempting to use custom (non-built-in) synth instruments without enabling this feature first
• Attempting to fit more code into a Sonic Pi buffer than is currently supported

Solutions include:

• Using officially supported Sonic Pi syntax to replace any 'non-standard' commands
• Checking the Preferences panel to make sure that options such as 'Enable external synths/FX' are turned on if desired
• Splitting large amounts of code between separate Sonic Pi buffers and syncing them up with the cue and sync commands
• Storing large amounts of code in one or more separate text files and using the run_file command to run them

When playing samples or synths, or using FX, it is possible to change various opts (eg amp:, lpf: etc) to affect the sound in various ways. Sometimes, it may be possible to give opts particular values that cause uncomfortable sounds - for example, values that are far outside their 'normal' range.

By default, Sonic Pi mostly prevents you from doing this, by ensuring that one of the settings in the Preferences panel/main menu, Audio > 'Safe mode', is turned on. This makes sure you are only allowed to enter 'reasonable' opt values. However, this setting may have been turned off. The solution is to make sure that 'Safe mode' is turned on. Note that this automatic validation does not currently apply to custom (non-built-in) synths or FX.

The SC3 plugins for SuperCollider may not be installed correctly on your system. See BUILD-LINUX.md. If your Linux distribution does not provide a prebuilt package of the SC3 plugins, you can build them from the SC3 plugins source code.

Don't worry! Here's some ways you can look for more clues, or ask for help:

Searching the GitHub Issues page is useful if your problem is not covered by this guide. Since there are often many different root causes for a single type of issue, (for example, Sonic Pi failing to start up), it's worth knowing a little about the most effective way to search the issues. The more relevant your search is to your exact issue, the more likely it is that you'll be able to find matching issues that already exist and avoid adding a duplicate, or the more likely it is that you'll know that your specific error is unique and needs its own issue, instead of adding noise to an issue that describes a different error message.

If your issue is about Sonic Pi failing to start up, then you will usually see a pop up window appear, that says so. However, the message on the popup is usually a fairly generic one. If you click the button that says 'Show Details...', then you will see an error report that can be copied and pasted into an issue on the GitHub page. Before you do that though, if you see errors in this report such as 'Critical error! Could not boot Sonic Pi Server.', or 'Critical Error. Unable to connect to server..' - these again are just generic errors that can have many different root causes. Instead, look for much more specific error messages, particularly in details from the log files scsynth.log, server-output.log and/or server-errors.log. (For example, you might see something like: SC_PortAudioDriver: PortAudio failed at Pa_OpenStream with error: 'Device unavailable'). Then, you can use words from these specific errors to search the existing GitHub issues. It's more likely that you'll find the right matching issue or know better that your problem hasn't been raised yet.

If you know your version of Sonic Pi is up-to-date, there's nothing relevant in the common issues and solutions in this guide, and you haven't found any existing issues on the GitHub Issues page that match your specific errors or situation, then it's fine to add a new one there. Keep in mind that 1) the smaller the list of issues the better, (so that it's easier for the developers to manage!) but also 2) it's helpful when each issue's details are as unique as possible (so that we can see every kind of issue separately at a glance). If you're going to raise a new issue, then the more information you can provide about your problem, and the setup of your Sonic Pi system, the better. There are many details that will be useful for helping other people to troubleshoot with you. Some of these might include:

• Your computer's Operating System (and which version).
• Your version of Sonic Pi.
• Information from the log files. See The log files above for details.
• (Minimal) examples of any code snippets you were trying to run.
• Detailed steps or descriptions of what you were doing, what happened, and what you were expecting to happen instead.
• Ideas about possible causes and/or solutions, if you have any. (Even better, send us a pull request!)