Installation on Raspberry Pi 4 (Debian 12 Bookworm arm64) Fails Without Repository Downgrade/Upgrade Workaround

[dseal-lightsonic]

Expected Behavior

After setting up the official Microsoft Debian 12 (bookworm) repository on a clean Raspberry Pi OS (64-bit) installation, running sudo apt-get install aziot-edge should successfully install the IoT Edge runtime and its dependencies. Following guidelines from: https://learn.microsoft.com/en-us/azure/iot-edge/how-to-provision-single-device-linux-symmetric?tabs=azure-portal%2Cdebian

Current Behavior

The installation fails with the error:

1. Package Not Found Error: Even after correcting repositories, apt sometimes enters a state where it reports E: Unable to locate package aziot-edge, despite the repository being configured correctly and apt-get update completing successfully.

The only way to achieve a successful installation was to apply a specific workaround.

Steps to Reproduce

1. Start with a Raspberry Pi 4 running Raspberry Pi OS (64-bit).
2. Run a cleanup script to ensure no previous IoT Edge components are installed. The script I used was:

#!/bin/bash
# This script cleans up the Azure IoT Edge installation to simulate a clean system.
# It should be run with sudo.

set -e

echo "--> Stopping and purging IoT Edge packages..."
apt-get purge -y aziot-edge aziot-identity-service

echo "--> Removing dummy packages (if any)..."
# The '|| true' prevents the script from exiting if the package isn't found
apt-get purge -y libtss2-esys0 || true

echo "--> Removing leftover dependencies..."
apt-get autoremove -y

echo "--> Removing Microsoft repository configuration..."
rm -f /etc/apt/sources.list.d/microsoft-prod.list
rm -f /etc/apt/trusted.gpg.d/microsoft.gpg

echo "--> Cleaning up downloaded files in current directory..."
# This command will be run from the user's home directory if they run 'sudo ~/script.sh'
# A safer way is to specify the path if known, e.g., /root/ or ~/
rm -f ./*.deb ./*.control

echo "--> Updating package lists..."
apt-get update

echo "Cleanup complete. The system is ready for a fresh installation test."

3. Execute the following sequence to set up the repository:

    # Step A: Install the CORRECT Debian 12 repository config.
    curl https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
    sudo apt install -y ./packages-microsoft-prod.deb
    # Step B: Intentionally DOWNGRADE to the incorrect Debian 11 repository config.
    # This step appears to be necessary to unblock the corrupted package state.
    curl https://packages.microsoft.com/config/debian/11/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
    sudo apt install -y --allow-downgrades ./packages-microsoft-prod.deb

    # Step C: UPGRADE back to the correct Debian 12 repository config.
    # This final step leaves the system in a state where installation can succeed.
    curl https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
    sudo apt install -y ./packages-microsoft-prod.deb

4. Update the package lists and install:

    sudo apt-get update
    sudo apt-get install aziot-edge

This sequence succeeds, whereas just installing the Debian 12 repository directly (Step A only) would fail.

If you just run the suggested commands from https://learn.microsoft.com/en-us/azure/iot-edge/how-to-provision-single-device-linux-symmetric?tabs=azure-portal%2Cdebian, you get Package Not Found Error. See logs:

root@raspberrypi:~# curl https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb > ./packages-microsoft-prod.deb
sudo apt install ./packages-microsoft-prod.deb
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  4304  100  4304    0     0  30907      0 --:--:-- --:--:-- --:--:-- 30964
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'packages-microsoft-prod' instead of './packages-microsoft-prod.deb'
packages-microsoft-prod is already the newest version (1.1-debian12).
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
root@raspberrypi:~# sudo apt-get update; \
  sudo apt-get install moby-engine
Hit:1 http://deb.debian.org/debian bookworm InRelease
Hit:2 http://archive.raspberrypi.com/debian bookworm InRelease
Hit:3 http://deb.debian.org/debian-security bookworm-security InRelease
Hit:4 http://deb.debian.org/debian bookworm-updates InRelease
Reading package lists... Done
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
moby-engine is already the newest version (28.3.2-debian12u1).
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
root@raspberrypi:~# sudo apt-get update; \
  sudo apt-get install aziot-edge
Hit:1 http://deb.debian.org/debian bookworm InRelease
Hit:2 http://deb.debian.org/debian-security bookworm-security InRelease
Hit:3 http://archive.raspberrypi.com/debian bookworm InRelease                   
Hit:4 http://deb.debian.org/debian bookworm-updates InRelease                    
Reading package lists... Done
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
E: Unable to locate package aziot-edge
root@raspberrypi:~# 

Context (Environment)

Device Information

• Host OS: Raspberry Pi OS (64-bit) (based on Debian 12 Bookworm)
• Architecture: arm64
• Container OS: Linux containers

Runtime Versions

• aziot-edged: 1.5.21-1 (version installed after successful workaround)
• Edge Agent: N/A (issue occurs during runtime installation)
• Edge Hub: N/A (issue occurs during runtime installation)
• Docker/Moby: 28.3.2-debian12u1

Logs

Successful logs using workaround:

  
sudo ./provision_rpi_iot_edge.sh 
  
  =================================================
  RASPBERRY PI IOT EDGE PROVISIONING SCRIPT (V2.3)
  =================================================
  [2025-07-14 15:08:16] Starting Raspberry Pi IoT Edge provisioning...
  [2025-07-14 15:08:16] Ensuring 'contrib' and 'non-free' repositories are enabled...
  [2025-07-14 15:08:16] Repositories are already correctly configured.
  [2025-07-14 15:08:16] Setting up Microsoft packages repository using the 12-11-12 workaround...
  [2025-07-14 15:08:16] --> Step 1/3: Installing Debian 12 config...
  Reading package lists... Done
  Building dependency tree... Done
  Reading state information... Done
  Note, selecting 'packages-microsoft-prod' instead of './packages-microsoft-prod.deb'
  packages-microsoft-prod is already the newest version (1.1-debian12).
  0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
  [2025-07-14 15:08:17] --> Step 2/3: Downgrading to Debian 11 config...
  Reading package lists... Done
  Building dependency tree... Done
  Reading state information... Done
  Note, selecting 'packages-microsoft-prod' instead of './packages-microsoft-prod.deb'
  The following packages will be DOWNGRADED:
    packages-microsoft-prod
  0 upgraded, 0 newly installed, 1 downgraded, 0 to remove and 0 not upgraded.
  Need to get 0 B/3,134 B of archives.
  After this operation, 43.0 kB of additional disk space will be used.
  Get:1 /root/packages-microsoft-prod.deb packages-microsoft-prod all 1.0-debian11.1 [3,134 B]
  dpkg: warning: downgrading packages-microsoft-prod from 1.1-debian12 to 1.0-debian11.1
  (Reading database ... 152134 files and directories currently installed.)
  Preparing to unpack .../packages-microsoft-prod.deb ...
  Unpacking packages-microsoft-prod (1.0-debian11.1) over (1.1-debian12) ...
  dpkg: warning: unable to delete old directory '/etc/debsig/policies/EB3E94ADBE1229CF': Directory not empty
  dpkg: warning: unable to delete old directory '/etc/debsig/policies': Directory not empty
  dpkg: warning: unable to delete old directory '/etc/debsig': Directory not empty
  Setting up packages-microsoft-prod (1.0-debian11.1) ...
  
  Configuration file '/etc/apt/sources.list.d/microsoft-prod.list'
   ==> Deleted (by you or by a script) since installation.
   ==> Package distributor has shipped an updated version.
     What would you like to do about it ?  Your options are:
      Y or I  : install the package maintainer's version
      N or O  : keep your currently-installed version
        D     : show the differences between the versions
        Z     : start a shell to examine the situation
   The default action is to keep your current version.
  *** microsoft-prod.list (Y/I/N/O/D/Z) [default=N] ? Y
  Installing new version of config file /etc/apt/sources.list.d/microsoft-prod.list ...
  N: Download is performed unsandboxed as root as file '/root/packages-microsoft-prod.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
  [2025-07-14 15:08:25] --> Step 3/3: Upgrading back to Debian 12 config...
  Reading package lists... Done
  Building dependency tree... Done
  Reading state information... Done
  Note, selecting 'packages-microsoft-prod' instead of './packages-microsoft-prod.deb'
  The following packages will be upgraded:
    packages-microsoft-prod
  1 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
  Need to get 0 B/4,304 B of archives.
  After this operation, 43.0 kB disk space will be freed.
  Get:1 /root/packages-microsoft-prod.deb packages-microsoft-prod all 1.1-debian12 [4,304 B]
  apt-listchanges: Reading changelogs...       
  (Reading database ... 152127 files and directories currently installed.)
  Preparing to unpack .../packages-microsoft-prod.deb ...
  Unpacking packages-microsoft-prod (1.1-debian12) over (1.0-debian11.1) ...
  Setting up packages-microsoft-prod (1.1-debian12) ...
  Installing new version of config file /etc/apt/sources.list.d/microsoft-prod.list ...
  File /usr/share/keyrings/microsoft-prod.gpg is missing. Installing...
  N: Download is performed unsandboxed as root as file '/root/packages-microsoft-prod.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
  [2025-07-14 15:08:27] Repository workaround applied. Cleaning up...
  [2025-07-14 15:08:27] Microsoft packages configured. Running apt update.
  Hit:1 http://deb.debian.org/debian bookworm InRelease
  Hit:2 http://deb.debian.org/debian-security bookworm-security InRelease        
  Hit:3 http://archive.raspberrypi.com/debian bookworm InRelease                                      
  Hit:4 http://deb.debian.org/debian bookworm-updates InRelease                                       
  Get:5 https://packages.microsoft.com/debian/12/prod bookworm InRelease [3,618 B]
  Get:6 https://packages.microsoft.com/debian/12/prod bookworm/main all Packages [573 B]
  Get:7 https://packages.microsoft.com/debian/12/prod bookworm/main armhf Packages [15.6 kB]
  Get:8 https://packages.microsoft.com/debian/12/prod bookworm/main arm64 Packages [28.1 kB]
  Get:9 https://packages.microsoft.com/debian/12/prod bookworm/main amd64 Packages [102 kB]
  Fetched 150 kB in 1s (245 kB/s)    
  Reading package lists... Done
  [2025-07-14 15:08:29] Container engine (Docker/Moby) is already installed and working.
  [2025-07-14 15:08:29] Installing Azure IoT Edge runtime...
  Reading package lists... Done
  Building dependency tree... Done
  Reading state information... Done
  The following additional packages will be installed:
    aziot-identity-service libtss2-tctildr0
  The following NEW packages will be installed:
    aziot-edge aziot-identity-service libtss2-tctildr0
  0 upgraded, 3 newly installed, 0 to remove and 5 not upgraded.
  Need to get 0 B/6,145 kB of archives.
  After this operation, 30.1 MB of additional disk space will be used.
  Selecting previously unselected package libtss2-tctildr0:arm64.
  (Reading database ... 152134 files and directories currently installed.)
  Preparing to unpack .../libtss2-tctildr0_3.2.1-3_arm64.deb ...
  Unpacking libtss2-tctildr0:arm64 (3.2.1-3) ...
  Selecting previously unselected package aziot-identity-service.
  Preparing to unpack .../aziot-identity-service_1.5.6-1_arm64.deb ...
  Unpacking aziot-identity-service (1.5.6-1) ...
  Selecting previously unselected package aziot-edge.
  Preparing to unpack .../aziot-edge_1.5.21-1_arm64.deb ...
  useradd warning: edgeagentuser's uid 13622 is greater than SYS_UID_MAX 999
  useradd warning: edgehubuser's uid 13623 is greater than SYS_UID_MAX 999
  Unpacking aziot-edge (1.5.21-1) ...
  Setting up libtss2-tctildr0:arm64 (3.2.1-3) ...
  Setting up aziot-identity-service (1.5.6-1) ...
  Created symlink /etc/systemd/system/sockets.target.wants/aziot-certd.socket → /lib/systemd/system/aziot-certd.socket.
  Created symlink /etc/systemd/system/sockets.target.wants/aziot-identityd.socket → /lib/systemd/system/aziot-identityd.socket.
  Created symlink /etc/systemd/system/sockets.target.wants/aziot-keyd.socket → /lib/systemd/system/aziot-keyd.socket.
  Created symlink /etc/systemd/system/sockets.target.wants/aziot-tpmd.socket → /lib/systemd/system/aziot-tpmd.socket.
  Setting up aziot-edge (1.5.21-1) ...
  ===============================================================================
  
                                Azure IoT Edge
  
    IMPORTANT: Please configure the device with provisioning information.
  
    Please create a new system configuration.
  
    You can quickly configure the device for manual provisioning with
     a connection string using:
  
      sudo iotedge config mp --connection-string '...'
  
    For other provisioning options, copy the template file 
    at /etc/aziot/config.toml.edge.template to /etc/aziot/config.toml,
    update it with your device information, then apply the configuration to
    the IoT Edge services with:
  
      sudo iotedge config apply
  
  ===============================================================================
  Created symlink /etc/systemd/system/sockets.target.wants/aziot-edged.mgmt.socket → /lib/systemd/system/aziot-edged.mgmt.socket.
  Created symlink /etc/systemd/system/multi-user.target.wants/aziot-edged.service → /lib/systemd/system/aziot-edged.service.
  Created symlink /etc/systemd/system/sockets.target.wants/aziot-edged.workload.socket → /lib/systemd/system/aziot-edged.workload.socket.
  Processing triggers for man-db (2.11.2-2) ...
  Processing triggers for libc-bin (2.36-9+rpt2+deb12u12) ...
  [2025-07-14 15:08:36] IoT Edge runtime installation completed successfully.
  
  =============================================
  ACTION REQUIRED: PROVISION YOUR DEVICE
  =============================================
  The IoT Edge runtime is installed.
  You now need to provision it with your device connection string from Azure.
  
  1. Get your connection string from the Azure Portal.
  
  2. Run these commands on the device, replacing the placeholder:
  
     sudo iotedge config mp --connection-string 'YOUR_CONNECTION_STRING_HERE'
     sudo iotedge config apply
  
  3. Verify the setup after a minute:
     sudo iotedge system status
  =============================================
  [2025-07-14 15:08:36] Script finished.
  root@raspberrypi:~# 

Additional Information

This issue was discovered after a long troubleshooting session. The initial state of the OS package manager (apt) appeared to be corrupted, preventing a straightforward installation. Standard fixes (apt-get -f install, dpkg --configure -a, cache cleaning) were not sufficient to resolve the problem.

The key finding is that the downgrade -> upgrade cycle of the packages-microsoft-prod configuration package was the only method that could reliably repair the system's state and allow aziot-edge and its dependencies to be found and installed correctly. This may suggest that the Debian 11 package's pre/post-installation scripts perform a cleanup action that the Debian 12 package does not, which is necessary on a system in this specific state.