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. Problems booting Bela from the SD card
  6. Speaker does not work
  7. Changes to the code are not reflected in the program
  8. “No rule to make target” error
  9. “InsecurePythonWarning” when using
  10. Stuck in a reboot loop

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

Problems booting Bela from the SD card

If you are using Bela Mini, a correctly flashed SD card will boot properly straight away.

If you are using Bela, the SD card booting will depend on the content of the in-built memory, or eMMC. The following conditions will mean that Bela will not boot correctly from the SD card and may not boot at all:

  • You have Bela v0.3.4 or newer on your SD card, and Bela v0.3.3 or earlier image on the eMMC
  • Your BeagleBone Black has the factory-set BeagleBone image on the eMMC

In order to be able to boot from the SD card, use one of the following options:

Option 1: Use jumper wires

Use this if you have 3 jumper wires available.

  • connect P8_45 and P8_46 to 3.3V (P9_03 and P9_04) and connect P8_44 to GND (P9_01). Check out the pin diagram here.
  • insert the SD card
  • power on the board
  • it will boot from the SD card
  • jump to Common steps below

Option 2

Use this if you have ssh access to the image on the eMMC.

  • remove SD card
  • plug the board into the host over USB. It will boot from the eMMC.
  • ssh to the board, e.g.:
    • if the eMMC contains a image, do ssh debian@beaglebone.local, password temppwd, or anything else needed to log into it (there have been many versions over time, some of them may require a domain/user/password to access them)
    • if the eMMC contains a Bela image, do ssh root@
  • run on the board the following commands:
    sudo dd if=/dev/zero of=/dev/mmcblk1 bs=1024k count=50
    sudo dd if=/dev/zero of=/dev/mmcblk1p1 bs=1024k count=50
    sudo dd if=/dev/zero of=/dev/mmcblk0 bs=1024k count=50
    sudo dd if=/dev/zero of=/dev/mmcblk0p1 bs=1024k count=50

    probably, 2 or more of these commands will fail, but that’s just fine.*

  • insert SD card and reboot. It will boot from the SD card
  • jump to Common steps below

* : what we are trying to do is to make the eMMC unbootable, so that the board will always boot from the SD card. So, we try to write zeros to the beginning of the boot partition. This is supposed to be /dev/mmcblk1p1, hence writing to /dev/mmcblk1 should be fine. However, some board will have the eMMC on /dev/mmcblk0p1. The reason we have for the multiple commands above is to cover both cases, which is also why some of them will fail, and that is just fine.

Option 3

Use this option if you do not have ssh access to the image on the eMMC and you do not have 3 jumper wires available.

  • disconnect power from the board
  • remove the Bela cape (see here)
  • insert the SD card in the slot
  • press the “USER” button on the BeagleBone (at the back just above the SD card slot) and hold it while powering up the Beaglebone.
  • jump to Common steps below and come back here for the final two steps once you are done
  • power off the board and put the Bela cape back on
  • power on the board. It should now successfully boot from the SD card without need to press the USER button.

Common steps

  • Once the board boots successfully, check that you can load the Bela IDE: open a web browser and go to the address bela.local/ (see here for more details). You should then run one of the following commands on the board (either in the console at the bottom of the Bela IDE, or after sshing into the board):
    • if you have a Bela image on the eMMC and you want to keep using it in its current state: /opt/Bela/ This should restore functionality of the image on the eMMC, but if there is an SD card inserted, it will boot from the SD card.
    • if you have a image on the eMMC, or if you want to update the Bela image on the eMMC with the one that is on the SD card, then run /opt/Bela/ Note: this will delete the content of the eMMC, possibly causing data loss.

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.

Stuck in a reboot loop

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.

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 board will reboot, and the program will begin to run again. However, holding down the button for more than 2 seconds 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

To disable the program that’s running at startup, SSH into your board if you’re not in already with the following:

$ ssh root@

If you can SSH in, you’ll see a Bela loading screen on the terminal. If you see this, enter this line to disable the program running on startup:

$ make -C /root/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.