MuPiBox Documentation MuPiBox Classic

The box hangs when shutting down

When switching off, the box shows the goodbye picture but does not shut down properly, and cannot be started again with the on/off button. Only discon…

When switching off, the box shows the goodbye picture but does not shut down properly, and cannot be started again with the on/off button. Only disconnecting the power helps?

Common cause: the pin is assigned twice

Boxes with an OnOff SHIM or a similar button use the overlay gpio-poweroff, so that the Raspberry Pi sends a signal to the board when shutting down. If this overlay appears twice in the file /boot/config.txt, the box hangs when shutting down.

That happens if you had to enter a driver of your own for your display and its line already contains the overlay, for example:

dtoverlay=vc4-fkms-v3d,gpio-poweroff,gpiopin=4,active_low=1

Earlier versions of the update did not recognise this line and appended a second definition:

dtoverlay=gpio-poweroff,gpiopin=4,active_low=1

How to check and fix it

Sign in to the box via SSH (or open a terminal in the DietPi dashboard) and look for the overlay:

grep -n gpio-poweroff /boot/config.txt

On newer systems (DietPi with Debian 13 “Trixie”) the file is at /boot/firmware/config.txt. Use that path in all commands on this page then.

  • One line (whether standalone or as a parameter of another overlay): fine, the cause lies elsewhere.
  • Two or more lines with gpio-poweroff: keep the line that belongs to your display and remove the additional standalone line dtoverlay=gpio-poweroff,gpiopin=4,active_low=1. You can edit the file with sudo nano /boot/config.txt.

Restart the box afterwards. The pin is also in the box's configuration (shim.poweroffPin) and must match what is in the line (GPIO assignment).

If it is not that

  • If music is still playing when switching off, it is paused before the goodbye sound. If the box still hangs, look in the logs (Logs and status): the log shutdown_control.log belongs to switching off with the button. It is kept in memory and is gone once the power is off - so look at it while the box is still running.
  • Check the power supply: voltage dips during shutdown can make it hang.
  • If that does not help, ask the community or report the bug on GitHub (splitti/MuPiBox). Download the support info and the log shutdown_control.log for it (Logs and status).
© 2026 MuPiBox