Troubleshooting Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides technical information for diagnosing and resolving issues encountered when using the safe64switch tool. The tool is designed to safely transition Raspberry Pi OS from a 32-bit kernel to a 64-bit kernel by modifying system configuration files while maintaining backups for recovery.
Sources: README.md:1-5, safe64.sh:1-5
Execution Failures and Error Handling
The script employs strict error handling to prevent system corruption. It is configured to exit immediately if any command fails, ensuring that a partial or broken configuration is not written to the boot partition.
Script Termination Logic
The script uses the set -e directive. This means that if any command returns a non-zero exit status, the script will terminate immediately. This is a primary safeguard for the /boot/config.txt modification process.
Sources: safe64.sh:7
Hardware Validation Error
A common point of failure is the hardware check. The script verifies the target environment by inspecting the device tree model. If the string "Raspberry Pi" is not found in /proc/device-tree/model, the script will exit with an error message: "Error: Not running on a Raspberry Pi. Exiting."
Sources: safe64.sh:12-16
The following flowchart illustrates the execution and validation logic:
The logic ensures that configuration changes only occur on supported hardware.
Sources: safe64.sh:7-34
Configuration Issues
Troubleshooting typically involves verifying the state of /boot/config.txt and the backup file.
Backup Recovery
Before any modifications are made, the script creates a backup of the original configuration. If the system fails to boot or behaves unexpectedly after running the script, the original state can be restored manually from the backup file.
| Original File | Backup Location | Purpose |
|---|---|---|
/boot/config.txt | /boot/config.txt.bak | Recovery of original 32-bit configuration |
Sources: safe64.sh:19-20
Parameter Verification
If the 64-bit kernel does not load, verify that the following lines exist in /boot/config.txt:
arm_64bit=1: Enables the 64-bit kernel mode.gpu_mem=16: Sets the minimum GPU memory to optimize performance (if applied).
The script uses grep -q to check if these settings already exist before appending them, preventing duplicate entries.
Sources: safe64.sh:23-32
Environment and Permissions
Root Privileges
The script modifies files in the /boot/ directory, which requires root permissions. Failure to run with sudo will result in a permission denied error, causing the script to exit immediately due to the set -e flag.
# Correct usage
sudo ./safe64.sh
Sources: README.md:16, safe64.sh:7
Script Permissions
If the script fails to start with "Permission denied", ensure the execution bit is set for the file.
chmod +x safe64.sh
Sources: README.md:15
Automated Quality Checks
The repository includes a ShellCheck workflow to ensure script integrity and follow best practices. If modifying the script for custom troubleshooting, ensure it passes these automated checks.
| Workflow File | Tool | Purpose |
|---|---|---|
.github/workflows/shellcheck.yml | ShellCheck | Static analysis for shell scripts |
Sources: .github/workflows/shellcheck.yml:1-15
Summary
Troubleshooting safe64switch involves verifying hardware compatibility, ensuring root execution permissions, and validating the contents of /boot/config.txt. The presence of /boot/config.txt.bak provides a failsafe mechanism to revert changes if the 64-bit kernel transition causes system instability.