Table of Contents
Fixing the “UUIDv4 is expected” Error in Zabbix 7 Template Imports
When working with Zabbix 7.0 and custom YAML templates, many users encounter the infamous error:
Invalid parameter "/1/uuid": UUIDv4 is expected.The Problem
At first glance, this message is confusing. Many assume it refers to a missing field or a wrong format.
In reality, Zabbix 7 introduced strict validation for template UUIDs.
Every object (templates, items, discovery rules, triggers) now requires a valid UUIDv4 identifier.
The tricky part: Zabbix does not accept the usual UUID format with hyphens (like
36a4c36e-15a8-43dc-9287-99780609f339).
Instead, it requires a 32-character hex string without hyphens, such as:
36a4c36e15a843dc928799780609f339
Why This Happens
If you generate UUIDs manually or with a script, they may not conform to the
UUIDv4 specification (RFC 4122 / RFC 9652).
Specifically, the version and variant bits must be set correctly.
Even if your string has the right length, Zabbix checks the internal bit pattern.
An invalid one results in the error.
The Solution
- Generate UUIDv4 values with correct version/variant bits.
- Strip hyphens so that the result is a continuous 32-character hex string.
- Ensure every element in your YAML has a unique UUID (template, items, triggers, etc.).
How to Generate Correct UUIDs
On Linux or macOS:
uuidgen | tr -d '-'
Online generators like uuidgenerator.net/version4
also work, as long as you remove the hyphens.
Takeaway
If your import fails with UUIDv4 is expected, the issue is not your template’s logic,
but simply the format of the UUIDs.
Replacing them with valid, hyphen-free UUIDv4 strings solves the problem instantly.
Once all UUIDs are valid, your custom template will import successfully into Zabbix 7.
The following script processes any Zabbix template (.yaml), identifies all uuid: fields, and replaces them with valid, RFC-compliant UUIDv4 values (32 hexadecimal characters).
import uuid
import yaml
import sys
def new_uuid():
“””Generate a valid UUIDv4 in 32-hex format (no hyphens).”””
return uuid.uuid4().hex
def replace_uuids(obj):
“””Recursively replace uuid fields in a Zabbix template.”””
if isinstance(obj, dict):
return {k: (new_uuid() if k == “uuid” else replace_uuids(v)) for k, v in obj.items()}
elif isinstance(obj, list):
return [replace_uuids(i) for i in obj]
else:
return obj
def fix_template(in_file, out_file):
with open(in_file, “r”, encoding=”utf-8″) as f:
data = yaml.safe_load(f)
fixed = replace_uuids(data)
with open(out_file, “w”, encoding=”utf-8″) as f:
yaml.dump(fixed, f, sort_keys=False, allow_unicode=True)
print(f”✅ Fixed UUIDs written to {out_file}”)
if __name__ == “__main__”:
if len(sys.argv) != 3:
print(“Usage: python fix_uuid.py input.yaml output.yaml”)
else:
fix_template(sys.argv[1], sys.argv[2])
📌 Using:
python fix_uuid.py old_template.yaml fixed_template.yaml