PVE disk inspection connected to UptimeKuma - the 404 pitfall and the final script

Published: 2025-05-14

Read first The previous article showed how to push the PVE host’s LVM-Thin usage to UptimeKuma. After following the instructions, some readers got a 404 when the script used curl. This article explains the cause, fixes the script, and provides an optional upgrade path. Follow along from scratch and you should succeed on the first try.

1 Phenomenon: `curl ... 404`

curl -fsS --retry 3 \
     "${PUSH_URL}?status=up&msg=OK" \
     -H 'Content-Type: application/json' \
     --data-raw "$result"
# ↳ curl: (22) The requested URL returned error: 404

The same URL works in a browser or with curl GET:

{"ok":true}

2 Reason: Older UptimeKuma versions only support GET/HEAD for push

Once curl adds --data-raw/-d, the HTTP method becomes POST. The push route in Kuma <= 1.23.x only registers GET/HEAD, so the request returns 404 directly. Many people in the community reported the same issue, and GitHub Issue #3267 is still marked as a feature request. (GitHub)

A Reddit discussion also confirmed that “POST will get 404, and there is no official solution yet.” (Reddit)

3 Two ways out

The following article will focus on Plan A, guaranteed to be completed within 5 minutes. Plan B is placed at the end of the article for further reading.

4 Final script (pure GET version)

4.1 Configuration file remains unchanged

# /etc/lvm_check.conf
PUSH_URL="http://192.168.102.146:3001/api/push/E94XDnl557"

4.2 Push script `/usr/local/bin/lvm_kuma_push.sh`

#!/bin/bash
# Send the inspection result to UptimeKuma using GET, so it works with older versions.
source /etc/lvm_check.conf
[ -z "$PUSH_URL" ] && { echo "missing PUSH_URL"; exit 1; }

json="$(/usr/local/bin/lvm_check.sh)"
status=$(echo "$json" | jq -r '.status')
encoded_json=$(printf '%s' "$json" | jq -sRr @uri)

if [ "$status" = "ok" ]; then
  curl -fsS --retry 3 \
       "${PUSH_URL}?status=up&msg=OK&details=${encoded_json}"
else
  problem=$(echo "$json" | jq -c '.volumes')
  encoded_prob=$(printf '%s' "$problem" | jq -sRr @uri)
  curl -fsS --retry 3 \
       "${PUSH_URL}?status=down&msg=${encoded_prob}&details=${encoded_json}"
fi

Remove --data-raw and Content-Type completely so curl stays GET.
URL-encode the JSON you originally wanted to POST and append it to details=; you can still see the full content in Kuma’s Maintenance Log.

4.3 Cron unchanged

*/5 * * * * /usr/local/bin/lvm_kuma_push.sh >/dev/null 2>&1

5 Verification steps

Manually run the script

/usr/local/bin/lvm_kuma_push.sh

A green Up heartbeat should appear immediately in the Kuma web interface. 2. Simulate disk alarm

Temporarily change THRESHOLD=90 to 1 and run the script again.
Kuma immediately turns red and shows msg as the JSON list of triggered volumes.
Change it back to 90, and once the space is normal it returns to Up.

6 Extended reading: What should I do if I want to use POST?

Upgrade to Kuma 2.x beta 2.x begins to rebuild the backend, and the push routing has been improved in community PRs. You can try the beta before the official GA, at your own risk.

Reverse proxy forwarding Nginx example:

location /api/push/ {
    proxy_pass_request_body off;
    proxy_pass http://kuma:3001;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-Method $request_method;
}

Use Lua or middleware to rewrite POST into GET, as in the alertmanager-kuma-push project.

7 Summarize a picture

Root cause of 404: older Kuma push monitors do not recognize POST, so removing the body fixes it.
Zero dependencies: the script still only needs jq, bc, and curl.
Future-proof: once Kuma officially supports POST, you can add --data-raw back.

At this point, the PVE host disk inspection is successfully connected to UptimeKuma, and the 404 pitfall is solved. Hopefully you no longer have to worry about the disk filling up in the middle of the night.

lvm_check.sh  ──>  lvm_kuma_push.sh (GET)  ──>  Uptime Kuma Push Monitor
     ↑ JSON              ↑ URL 参数
     └─────── cron */5 ───────┘