Proxmox snapshot backup: fs-freeze hook fails with “bad substitution”

[OpenTV-0815]

When running OpenCCU as a VM on Proxmox, snapshot backups with the QEMU Guest Agent enabled consistently log the following error:

unable to freeze guest fs – syntax error: bad substitution
/etc/qemu/fsfreeze-hook

Observed behavior
• The backup itself completes successfully
• Proxmox falls back to a snapshot without fs-freeze
• The VM is not interrupted and continues running normally

Root cause (analysis)

The error indicates that the fsfreeze-hook is executed via /bin/sh (dash on Debian/Proxmox), while the script appears to contain bash-specific parameter substitution, leading to bad substitution.

Why this matters
• fs-freeze via QEMU Guest Agent is best practice for consistent snapshots
• Other Proxmox-targeted appliances (e.g. Home Assistant) handle this cleanly

This is not a critical issue, but a small compatibility/quality aspect when running OpenCCU under Proxmox.

Expectation

No immediate fix required — just wanted to report this behavior in case Proxmox compatibility is improved or documented in the future.

Thanks for your work on OpenCCU

[Baxxy13]

Logs from Proxmox:

INFO: Starting Backup of VM 106 (qemu)
INFO: Backup started at 2026-02-11 16:46:20
INFO: status = running
INFO: VM Name: RM-Test-VM-96
INFO: include disk 'scsi0' 'local-lvm:vm-106-disk-0' 6G
INFO: backup mode: snapshot
INFO: ionice priority: 7
INFO: creating Proxmox Backup Server archive 'vm/106/2026-02-11T15:46:20Z'
INFO: issuing guest-agent 'fs-freeze' command
ERROR: unable to freeze guest fs - child process has failed to execute fsfreeze hook: /etc/qemu/fsfreeze-hook: line 60: syntax error: bad substitution
INFO: issuing guest-agent 'fs-thaw' command
INFO: started backup task 'd6a556be-ff0d-40f7-ac3d-b05ee0fc9557'
INFO: resuming VM again

Logs from OpenCCU:

Feb 11 16:46:20 RM-Test-VM-96 user.info qemu-ga: info: guest-ping called
Feb 11 16:46:20 RM-Test-VM-96 user.info qemu-ga: info: guest-fsfreeze called
Feb 11 16:46:20 RM-Test-VM-96 user.info qemu-ga: info: executing fsfreeze hook with arg 'freeze'
Feb 11 16:46:20 RM-Test-VM-96 user.notice qemu-ga-freeze-hook: Executing /etc/qemu/fsfreeze-hook.d/regahss-flush.sh freeze
Feb 11 16:46:21 RM-Test-VM-96 user.info qemu-ga: info: guest-fsthaw called
Feb 11 16:46:21 RM-Test-VM-96 user.info qemu-ga: info: executing fsfreeze hook with arg 'thaw'

/var/log/qga-fsfreeze-hook.log:

Wed Feb 11 16:46:21 CET 2026: Executing /etc/qemu/fsfreeze-hook.d/regahss-flush.sh thaw
Wed Feb 11 16:46:21 CET 2026: /etc/qemu/fsfreeze-hook.d/regahss-flush.sh finished successfully

[OpenTV-0815]

Thanks for providing the logs

From what can be seen, the error does not appear to originate from the OpenCCU-specific hook script itself (regahss-flush.sh), but rather from the main wrapper script:

/etc/qemu/fsfreeze-hook

Proxmox reports:

line 60: syntax error: bad substitution

This usually indicates a shell compatibility issue (e.g. bash-specific parameter expansion being executed under /bin/sh).

The OpenCCU hook located in:

/etc/qemu/fsfreeze-hook.d/regahss-flush.sh

seems to execute correctly, as shown in the OpenCCU logs:

executing fsfreeze hook with arg 'freeze'
Executing .../regahss-flush.sh freeze
finished successfully

So:

• qemu-guest-agent is working properly
• The OpenCCU flush hook runs successfully
• The error likely comes from the wrapper script /etc/qemu/fsfreeze-hook

It might be worth checking whether the wrapper script uses bash-specific syntax while being executed with /bin/sh.

Overall, the backup itself completes successfully, so this seems to be a cosmetic/logging issue rather than a functional problem.

Thanks again for testing and sharing the logs!

[OpenTV-0815]

Additional Observation / Possible Root Cause

After further testing, the issue does not appear to be deterministic.
In some backup runs, fs-freeze completes without error, while in others the following occurs:

/etc/qemu/fsfreeze-hook: line 60: syntax error: bad substitution

The wrapper script /etc/qemu/fsfreeze-hook currently uses:
#!/bin/sh

On Debian-based systems, /bin/sh points to dash, which does not support certain Bash-specific parameter expansions (e.g. ${var//pattern/replacement}).

My current hypothesis is that the script may contain Bash-specific syntax that is only executed under certain code paths. If that code path is not triggered, the backup completes without error. If it is triggered, dash raises the bad substitution error.

I may be mistaken, but this could explain why the problem appears intermittently.

Switching the shebang to #!/bin/bash (if Bash syntax is intentionally used) might resolve the issue.

[Baxxy13]

OpenCCU seems to use the default fsfreeze-hook - Script from QEMU - Project:
https://gitlab.com/qemu-project/qemu/-/blob/master/scripts/qemu-guest-agent/fsfreeze-hook?ref_type=heads

Homeassistant-OS seems to use a different one:
https://github.com/home-assistant/operating-system/blob/dev/buildroot-external/rootfs-overlay/usr/libexec/haos-freeze-hook

There is another variant in the proxmox-repo:
https://github.com/proxmox/qemu/blob/master/scripts/qemu-guest-agent/fsfreeze-hook

But all are using #!/bin/sh which seems correct. As far as i know OpenCCU can't use #!/bin/bash.

[OpenTV-0815]

Thanks for the references.

The shebang is indeed #!/bin/sh, which is correct for OpenCCU.

However, the error "bad substitution" strongly indicates that the script
contains bash-specific parameter expansion which is not POSIX-compliant.

On OpenCCU, /bin/sh points to dash (not bash).
Dash does not support bash-style substitutions like:

${var//pattern/replace}

This would explain the syntax error during fs-freeze execution.

Since the same hook works on systems where /bin/sh is linked to bash
(e.g. some Debian-based systems), this could explain why the issue
does not appear everywhere.

So the problem may not be the shebang itself,
but non-POSIX-compatible shell syntax inside the script.

Just sharing this observation in case it helps narrowing down the root cause
— happy to assist further with testing if needed.

[Baxxy13]

Siehe: #3593