Your Pi Agent Isn't Flaky. It's Underpowered or Overheating, and the Logs Won't Say So.
Some nights your agent’s publish job finishes in four minutes. Other nights the same job takes fifteen, or an API call times out, or the run dies halfway through a file write. The USB SSD sometimes drops off the bus and comes back. Once, after a busy evening, the SD card came up with a corrupted file and the system went read-only.
You check the agent logs. Nothing useful. A timeout, maybe, or a write error with no cause attached.
That’s because the agent can’t see the problem. When the Pi’s supply voltage sags or the SoC gets too hot, the firmware quietly slows the CPU or the hardware starts misbehaving. Your code just sees a slower or less reliable machine. The Pi does keep a record, though. You just have to ask for it.
The symptoms, in plain terms
Power and heat problems tend to look like this:
- Jobs are slower on some runs with no change in code or input.
- Random timeouts in HTTP calls, model calls, or
git push, usually during the heaviest part of a job. - USB SSD disconnects, often with
reset high-speed USB deviceor I/O errors in the kernel log. - SD or SSD corruption after load spikes, such as several jobs starting at the same time.
- Problems that come and go with the weather or with where the Pi sits.
None of these prove a power or heat issue. But if you see more than one, check before you start rewriting your retry logic.
Check the throttle state
On Raspberry Pi OS, run:
vcgencmd get_throttled
You’ll get something like throttled=0x0 or throttled=0x50005. Zero means nothing has gone wrong since boot. Anything else is a bit field:
| Bit | Value | Meaning |
|---|---|---|
| 0 | 0x1 | Under-voltage detected now |
| 1 | 0x2 | ARM frequency capped now |
| 2 | 0x4 | Currently throttled |
| 3 | 0x8 | Soft temperature limit active now |
| 16 | 0x10000 | Under-voltage has occurred |
| 17 | 0x20000 | ARM frequency capping has occurred |
| 18 | 0x40000 | Throttling has occurred |
| 19 | 0x80000 | Soft temperature limit has occurred |
The low bits describe right now. The high bits are sticky: they stay set until the next reboot. So 0x50000 means under-voltage and throttling both happened at some point since boot, but neither is active this second. 0x50005 means under-voltage is active and the CPU is throttled right now.
Bash can decode it for you:
val=$(vcgencmd get_throttled | cut -d= -f2)
(( val & 0x1 )) && echo "under-voltage NOW"
(( val & 0x2 )) && echo "arm freq capped NOW"
(( val & 0x4 )) && echo "throttled NOW"
(( val & 0x8 )) && echo "soft temp limit NOW"
(( val & 0x10000 )) && echo "under-voltage has occurred"
(( val & 0x20000 )) && echo "arm freq capping has occurred"
(( val & 0x40000 )) && echo "throttling has occurred"
(( val & 0x80000 )) && echo "soft temp limit has occurred"
Two more readings help separate power from heat:
vcgencmd measure_temp # temp=58.4'C
vcgencmd measure_clock arm # frequency(...)=1500000000 (Hz)
If the clock is well below your model’s normal maximum while the CPU is busy, something is holding it down. A high temperature points at heat. The under-voltage bits point at power.
Finally, check the kernel log. Recent kernels report sags directly:
journalctl -k | grep -i voltage
Lines like Undervoltage detected! and Voltage normalised tell you exactly when it happened. Add -b -1 to look at the previous boot if the Pi has rebooted since.
If vcgencmd says permission denied, your user needs to be in the video group.
Log it over time
A single reading tells you about one moment. You want a history you can line up against job runs. This script appends throttle state, temperature, and clock to a CSV, and sends a Discord alert only when the throttle value changes:
#!/usr/bin/env bash
# /home/pi/agent/bin/pi-health.sh
set -uo pipefail
CSV="/home/pi/agent/logs/pi-health.csv"
LAST="/home/pi/agent/state/throttled.last"
mkdir -p "$(dirname "$CSV")" "$(dirname "$LAST")"
val=$(vcgencmd get_throttled | cut -d= -f2) || exit 1
temp=$(vcgencmd measure_temp | sed -E "s/temp=([0-9.]+).*/\1/")
hz=$(vcgencmd measure_clock arm | cut -d= -f2)
mhz=$(( hz / 1000000 ))
[[ -f "$CSV" ]] || echo "timestamp,throttled,temp_c,arm_mhz" > "$CSV"
echo "$(date -Is),$val,$temp,$mhz" >> "$CSV"
prev=$(cat "$LAST" 2>/dev/null || echo "0x0")
echo "$val" > "$LAST"
if (( val != prev )) && [[ -n "${DISCORD_WEBHOOK_URL:-}" ]]; then
msg="$(hostname): throttled $prev -> $val, temp ${temp}C, arm ${mhz}MHz"
curl -fsS -m 10 -H 'Content-Type: application/json' \
-d "{\"content\":\"$msg\"}" "$DISCORD_WEBHOOK_URL" >/dev/null 2>&1 \
|| echo "$(date -Is) alert send failed" >&2
fi
curl -f makes an HTTP error count as a failure instead of a silent success. Errors go to a generic message, so the webhook URL never ends up in a log. Because the sticky bits clear on reboot, you’ll also get one alert when the value drops back to 0x0 after a restart. That’s useful too.
Run it every five minutes with a systemd timer. Put the webhook in an env file with chmod 600, as plain KEY=value lines.
/etc/systemd/system/pi-health.service:
[Unit]
Description=Log Pi throttle, temp, and clock
[Service]
Type=oneshot
User=pi
EnvironmentFile=/home/pi/.config/agent/agent.env
ExecStart=/home/pi/agent/bin/pi-health.sh
/etc/systemd/system/pi-health.timer:
[Unit]
Description=Pi health every 5 minutes
[Timer]
OnBootSec=2min
OnUnitActiveSec=5min
[Install]
WantedBy=timers.target
sudo systemctl daemon-reload
sudo systemctl enable --now pi-health.timer
Line it up with job duration
The fastest way to connect throttling to slow jobs is to record the throttle value at the start and end of every heavy job. Add this to your job wrapper:
t0=$(date +%s); th0=$(vcgencmd get_throttled | cut -d= -f2)
node "$AGENT_DIR/publish.js"
th1=$(vcgencmd get_throttled | cut -d= -f2)
echo "$(date -Is),publish,$(( $(date +%s) - t0 )),$th0,$th1" >> "$AGENT_DIR/logs/jobs.csv"
If th1 has a sticky bit that th0 didn’t, the event happened during that job. After a couple of weeks, sort jobs.csv by duration. If the slow runs keep showing new bits, you’ve found your cause. For finer detail, match the job’s start and end timestamps against the rows in pi-health.csv.
Fix the cause
Monitoring tells you what’s happening. These changes stop it.
Use the official power supply. The Pi 5 is designed for the 27W USB-C supply, which delivers 5A at 5V. The Pi 4 needs a 5.1V, 3A USB-C supply. Phone chargers and laptop bricks often negotiate lower current or sag under load. On a Pi 5, a supply that can’t advertise 5A also makes the firmware limit total USB current, which hits USB SSDs hardest.
Use a short, thick cable. Thin or long USB-C cables drop voltage under load. A good supply on a bad cable still under-volts.
Give SSDs their own power. A USB SSD can pull a lot of current during heavy writes, and the Pi’s USB ports share a limited budget. A powered USB hub or an SSD enclosure with its own power input takes that load off the Pi. This is often the fix for “random” SSD disconnects.
Cool it. Add a heatsink at minimum. On a Pi 5, the official Active Cooler is the easy choice. Pi 4 and Pi 5 boards start throttling at around 80°C, and a bare board in a closed case under sustained load can get there.
Check the case and placement. A sealed plastic case in a cupboard next to a router traps heat. Give it airflow, or use a case with a fan.
Spread out heavy jobs. If your publish job, backup, and model calls all start at 3:00, they spike power and heat together. Stagger them by a few minutes, or chain them so one starts when the previous one finishes. That also helps if you’ve been running out of memory at the same hour.
Refuse to start when power is bad
Even with good hardware, add a preflight check that refuses to start a heavy job while the Pi is under-volted or already hot. A skipped run with a clear reason beats a corrupted file.
#!/usr/bin/env bash
# /home/pi/agent/bin/power-preflight.sh
set -uo pipefail
val=$(vcgencmd get_throttled | cut -d= -f2)
temp=$(vcgencmd measure_temp | sed -E "s/temp=([0-9]+).*/\1/")
problem=""
(( val & 0x1 )) && problem="under-voltage active ($val)"
(( temp >= 75 )) && problem="${problem:+$problem; }temp ${temp}C"
if [[ -n "$problem" ]]; then
echo "$(date -Is) preflight refused: $problem" >&2
if [[ -n "${DISCORD_WEBHOOK_URL:-}" ]]; then
curl -fsS -m 10 -H 'Content-Type: application/json' \
-d "{\"content\":\"$(hostname) skipped heavy job: $problem\"}" \
"$DISCORD_WEBHOOK_URL" >/dev/null 2>&1 || true
fi
exit 75
fi
Call it near the top of the wrapper, before the job does any writes. Exit code 75 is the conventional “temporary failure,” so a systemd unit shows a real failure and you can tell it apart from a code bug. Adjust the temperature threshold to suit your cooling.
Make this a standing check
Power and heat problems don’t announce themselves, so make the check part of every job. Grab one of the free prompts and turn it into a “review this wrapper for power preflight, health logging, and staggered schedules” routine before you add a new scheduled job. For ready-made health loggers, preflights, and the rest of the guardrails for unattended agents, the OpenClaw Agent Ops Toolkit collects them in one place. The Ultimate Bundle includes everything for $49.
More from the build log
Suggested
Want the full MarketMai stack?
Get the core MarketMai guides and operator playbooks in one premium bundle for $49.
View Bundle