Troubleshooting Guide

Table of contents

  1. Board will not power on
  2. bela.local produces a search result
  3. IDE does not load in the browser
  4. I can’t ssh into my board
  5. When I load the IDE I get a Beagleboard page
  6. My board won’t boot from the SD card
  7. Speaker does not work
  8. Changes to the code are not reflected in the program
  9. “No rule to make target” error
  10. “InsecurePythonWarning” when using
  11. Program running at boot and board not showing up

Board will not power on

When you plug in the USB cable to either Bela or Bela Mini, you should see a blue light appear on the BeagleBone or PocketBeagle, and a few seconds later, some blinking blue lights. If no lights appear, check your USB connection. If you have sensors or other electronics wired to your Bela, disconnect them. A short circuit between one of the power rails and ground can lead to the board not powering on.

If you bought a Bela Cape or Bela Mini Cape and installed it yourself, check that it is in the right orientation, securely seated, and (in the case of Bela Mini) that the soldering has no open or shorted pins.

If the board powers up to only a solid blue light, check the software image on the SD card or (in the case of Bela) the internal flash of the BeagleBone. See Updating Bela for details on installing a new image.

bela.local produces a search result

In some browsers, typing bela.local isn’t recognised as an address, and instead of loading the Bela IDE it produces a search result.

To avoid this, either enter http://bela.local, or bela.local/.

IDE does not load in the browser

Bela will boot when you plug it into a computer. After booting, you can then access the browser-based IDE from http://bela.local.

If you are unable to bring up the IDE in your browser, try the following:

  1. Check that the board is powered up. After 15 seconds or so, there should be a flashing blue “heartbeat” LED on the BeagleBone or PocketBeagle, indicating the board is powered and active. If not, see Board will not power on for suggestions.

  2. Wait a little. Bela typically takes 15-30 seconds to boot, and if a project is set to run automatically at boot, it can take up to 120 seconds to be ready to go.

  3. Check that the web address is correct. You can normally reach the IDE via the address http://bela.local (you may need the http so the browser does not interpret the address as a search). Depending on your system, you may also be able to load the IDE from the address or

  4. Check operating system drivers. If you are on MacOS X Catalina (10.15) or a very early version of Windows or MacOS, you may need to install the USB network driver. Visit the Get Started Guide for details on installing drivers.

  5. Restart your board. Especially if the IDE used to work and has stopped working, try removing power and plugging it back in.

  6. Check that the IDE is not disabled at boot. Visit the Scripts page for more info on how to run and look at start

  7. Update the board with the latest Bela image. See Updating Bela for details.

You can also check whether an external drive called BELABOOT shows up on your computer after you connect the board (this may also take 30 seconds). If the drive is present but you can’t bring up the IDE, it is probably a problem with your network driver or settings. If it is not present, then it could be a problem with the USB connection or with the software on the Bela board.

I can’t ssh into my board

Sometimes you may want to access your Bela device via the command line in a terminal instead of through the browser-based IDE (see using the command line for more).

If running ssh in the command line hangs and never connects, it is probably a network problem. Check whether you can load the IDE in the browser, and if not, see IDE does not load in the browser for further suggestions.

When running ssh you may also encounter this error message:

Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the ECDSA key sent by the remote host is
[there will be a long alpha numeric string here].
Please contact your system administrator.

The most common cause of this error is when you previously logged into another Bela board (or the same board with a different image) on the same IP address (usually or or bela.local). To fix it, you’ll have to generate a new key for the IP address.

Run this in the terminal for your laptop (not when you’re logged into your Bela board):

$ ssh-keygen -R

NOTE: If you’re using another IP address, use that in place of

When I load the IDE I get a Beagleboard page

This means that you have the image on the onboard memory (eMMC) of the Beaglebone Black instead of the Bela image. To resolve this you will need an SD card and some jumper wires. We will first flash the Bela image onto an SD card, boot the Bela from this SD card, and finally copy the contents of the SD card onto the onboard memory.

See our step-by-step guide to Flashing the eMMC.

My board won’t boot from the SD card

In the case of a Bela Starter Kit there are times when it will always boot from its onboard memory (eMMC) rather than from the SD card with the Bela image on it. We have a guide on how to force to board to boot from an SD card and then to make sure it continues to do so in the future.

Speaker does not work

Bela’s on-board speaker amplifiers require the board to be powered with an external 5V supply through the barrel cable connection, even if the board is already powered via USB. Check that you are powering externally.

You can also check that the mute-speaker command line flag is set to 0. See this page for details on command line arguments.

Changes to the code are not reflected in the program

If you make changes to your code and you’re not seeing any changes in your program when you build and run it, this is probably because your code is not being recompiled by the Makefile. This problem is often accompanied by really fast build times, because the Makefile isn’t doing any work. This is most likely due to the date on your board being incorrect, and should not happen if you are using the Bela IDE, but only when compiling projects from the terminal If the system date is wrong, this may interfere with compiling processes. The date is reset at every reboot to a default value and is brought up to date automatically when using the Bela IDE or any of the Bela scripts from the host. The solution is to either set the date manually on the board with the date command, or use any of the Bela scripts from the host, or simply just open the IDE tab in a browser and let it load. To ensure that your project files will rebuild after updating the date, you can clean the project. This can be done from the IDE using the broom icon in the project controls, or calling make PROJECT=projectname clean from the terminal.

“No rule to make target” error

This error could result from removing a source file from your project, while the old object file is still in the build/ folder.

To solve this, clean your project as explained above.

“InsecurePythonWarning” when using

InsecurePlatformWarning: A true SSLContext object is not available.

This would be caused by the lack of some optional python packages. To fix it:

# pip install requests[security]

(see here for more info)

If, after running the above, you get the error ImportError: cannot import name IncompleteRead, this is likely because your version of pip is too old (as it is the case in Ubuntu 14.04 LTS). To fix this, remove the current version of pip and install a more up-to-date version. See here for more info.

Program running at boot and board not showing up

If your board is set to run a program on boot and this program is very CPU intensive, you may struggle to access the board and the IDE, as the CPU is mostly busy servicing the running program. Here are some strategies if you find yourself in a reboot loop, starting from the easiest one first.

Ground the clock lines

You can prevent the program from starting altogether by silencing the McASP clock lines and the I2C or SPI lines communicating with the codec. How you do this depends on what board you are using:

  • for any board that uses the BeagleBone Black (Bela, CTAG): connect P9.20, P9.25, P9.29 and P9.31 to ground. Ground pins can be found on P9.01, P9.02, P9.43, P9.44, P9.45, P9.46, P8.01, P8.02. For CTAG, additionally connect P8.32 to ground.
  • for any board that uses the PocketBeagle (BelaMini, BelaMini Multichannel): connect P1.26 P1.29, P1.33, P1.36 to ground. Ground pins can be found on P1.16, P1.22, P2.15, P2.21. Shortly after you perform the above connections the program will stop running, the device should show up again and the IDE should start working again. From there you can disable the program from running on boot.

Use the Bela button

The key to resolving this is the button on the Bela cape. Pressing this button once kills the program that is currently running, and will temporarily free up some resources. However, the program will automatically restart and run again. If you hold down the button for more than 2 seconds, this will trigger a board shut down, and when you start it up again the reboot loop begins anew.

The key is to press the cape button very often. If you’re quick enough, systemctl will recognise that the bela_startup service is quitting too quickly and will temporarily disable it. This is effective in many cases but not guaranteed, especially if the project that runs on boot does lots of processing before calling render() (such as loading files from disk). Also note that this strategy is will not work on images prior to Bela v0.3.

Use the command line

Connect your board to your computer. In a terminal window, run the following to stop the program that’s running:

$ ssh -o StrictHostKeyChecking=no -o ConnectTimeout=1200 root@ make -C Bela stop nostartup

Try to load the IDE page in a browser

Plug the board into your computer and wait a few minutes for it to finish startup. Go to or bela.local in a browser window.

If the IDE loads, press the stop button on the Bela cape (again, this might take some time to be effective). Once the running project is stopped, change the Run on boot option to none at the top of the Settings tab.