Recently, a customer asked me:
“Hey — is it possible that VMware tag backup isn’t working?”
The reason: After a Full VM Restore (Restore to original location), the VM’s VMware tags were suddenly gone. In the restore log it basically said:
“These tags were not present at the time of backup — so I’m removing them.”
And that’s despite the fact that the tags were definitely set in production (otherwise the customer wouldn’t have been able to pick up the VM in their jobs using tag-based selection in the first place).
A test with another VM showed the same behavior. At that point it was clear: this wasn’t a one-off.
So how does Veeam get the idea that a VM has “no tags” — even though it does?
What is a VMware Tag (and why is it relevant for backups)?
VMware tags are metadata in vCenter that can be assigned to objects (for example, VMs). Typical use cases include:
- Organizational mapping (customer, environment, cost center)
- Technical classification (OS, SLA, app)
- Automation (backup scopes, policies, orchestration)
In Veeam, tags are often used to define dynamic job scopes (“Back up all VMs with Tag X”).
How Veeam “backs up” tags (and why this depends on vCenter)
Important: Veeam does not “invent” or “guess” tags. Veeam queries the information from vCenter during the backup job runtime and then writes it into the restore point metadata.
The process is roughly:
- Backup job starts
- Veeam opens a session to vCenter (vAPI)
- Veeam queries tag information/assignments
- Veeam writes this information into the backup metadata
- Veeam executes the Backup Process
In the log, for example, you can see the summary being written — but in the problematic case with an empty tag block:
... <Tags /> ...
If this tag query stays empty during backup, or the processing gets aborted/cut off, then later during restore there is simply nothing Veeam can “restore”.
Restore logic: why Veeam “removes” tags during restore
When restoring to the original location, the option “Restore VM Tags” is active. Veeam restores the tags by comparing: tags in the backup metadata vs. tags currently present on the restored VM.
- Result:
- Tags that were present in the backup → attach
- Tags that were not present in the backup, but are currently attached to the VM → remove
And that is exactly what happened in the customer case: the backup metadata incorrectly said “the VM had no tags” (<Tags />) — so the restore logic consistently removed the existing tags.
The real root cause: tag queries are too large → JSON length limit
In the detailed logging it was visible that Veeam queries the tags from vCenter via:
vmware.cis.tagging.TagAssociationStub.ListAttachedObjectsOnTags(...)
In the customer case (428 tags, plus many links/associations), the response from vCenter was so large that it hit a JSON limit (maxJsonLength). Result: the tag information is not processed correctly and effectively ends up as empty in the backup.
Important: it’s not only about the raw number of tags. This can happen with ~130 tags as well as with 400+ tags. What matters is the combination of:
- many tags
and - many objects/links attached to tags (associations)
Why don’t you see a “hard” error in the restore?
Because the restore job “only” works with what is stored in the restore point. If no tags were captured during backup (or they were stored as empty), then the restore has no knowledge of the original tags — and consistently removes everything that does not match the metadata state (if you restore to same location.
Fix for Veeam v12: split tag queries into smaller packages
To fix the issue, the tag query must be split into smaller requests — for example packages of 50 tags instead of “everything at once”.
For this, Veeam Backup & Replication v12 provides a registry key under:
Path: HKEY_LOCAL_MACHINE\SOFTWARE\Veeam\Veeam Backup and Replication\
Type: DWORD
Name: MaxTagsAssociationsPerOneApiTagsCall
Value: 1000 (default)
If you set this value, for example, to 50, then the tag association queries are split into smaller chunks, the response stays small enough — and the tag information is written properly into the backup metadata again.
In our test case, that was exactly the solution after running a new backup.
Fix in v13: smaller queries by default
In Veeam VBR v13, the problem is fundamentally fixed because tag queries are split into smaller requests by default. This prevents the response length from running into the maxJsonLength limitation.
Conclusion
Symptom: Restore removes tags / “Restored: 0, Removed: X”
Root cause: Tags were stored as empty in the backup (<Tags />) due to an oversized vCenter response
Fix: Chunking (v12 via registry), v13 by default