How To
Summary
A VIOS backup fails — either through an HMC-scheduled backup job or a manual `viosbr -backup` command
Objective
Root Cause
The viosbr backup process generates an XML file describing the VIOS configuration, pulling values from system configuration data (ODM) and device attributes. If any value included in that file contains an invalid or non-printable character — most commonly a stray control character (e.g. a backspace) left over from a configuration value that wasn't fully or cleanly updated in the past — the resulting XML file becomes invalid, and viosbr cannot complete the backup.
A typical example: a system attribute such as the hostname was changed at some point, and a stray, invisible character got saved into that value along with the intended text. The value may look correct or nearly correct when viewed casually, but the embedded character is enough to break the backup file.
Environment
A VIOS backup fails — either through an HMC-scheduled backup job or a manual viosbr -backup command — with an error similar to:
HSCL2970 The IOServer command has failed because of the following reason:
Backup XML file is not well formed - File copied into /home/ios/logs/viosbr_xml_not_well_formatted.<n> for debug purpose
ERROR- Backup File /home/ios/.viosbr.<n>/<filename> is not well formed
ERROR- Backup XML file is not well formed. Please contact IBM Support.
rc=255Manual CLI reproduction shows the same failure:
$ viosbr -backup -file /home/padmin/<filename>
Backup XML file is not well formed - File copied into /home/ios/logs/viosbr_xml_not_well_formatted.<n> for debug purpose
ERROR- Backup File /home/ios/.viosbr.<n>/<filename> is not well formed
ERROR- Backup XML file is not well formed. Please contact IBM Support.
Steps
Diagnostic and Resolution Steps
Step 1 — Identify where the error occurs in the backup file
Locate the most recent error file, automatically generated by viosbr when a backup fails:
ls -lt /home/ios/logs/viosbr_xml_not_well_formatted.*Search the file for non-printable/control characters using cat -v, which makes them visible (e.g. a NUL byte displays as ^@, a backspace as ^H):
cat -v /home/ios/logs/<file> | grep -n '\^@'If that returns nothing, broaden the search to catch any control character:
cat -v /home/ios/logs/<file> | grep -n '\^[A-Z]'This returns the line number(s) where the invalid character occurs.
Step 2 — Confirm which configuration item is affected
Using the line number(s) from Step 1, view the surrounding lines to identify which element the corrupted value belongs to:
sed -n '<N-5>,<N+5>p' /home/ios/logs/<file>This will typically show a device, interface, or attribute block (e.g. hostname, network interface, adapter description), which identifies the specific configuration item to correct.
Once identified, confirm the current value directly. For example, if the affected item is the system hostname attribute:
odmget -q "name=inet0 and attribute=hostname" CuAtReview the value carefully — an embedded invalid character will not necessarily display as blank space; it may simply make the value look slightly "off" (e.g. an extra or missing character) rather than obviously broken.
Step 3 — Correct the value
The affected value is corrected using the standard, supported system command for that configuration item — not a manual or direct edit of internal system data, which keeps the risk of this fix minimal. For example, to correct a corrupted hostname attribute:
chdev -l inet0 -a hostname=<correct_hostname>No reboot or downtime is required. This type of change takes effect immediately, updating both the stored configuration and the live system value, with no impact to the VIOS or any virtual machines it serves.
If the corruption is found in a different attribute or device, the equivalent supported command for that specific item is used instead — the same principle applies regardless of which value is affected.
Step 4 — Verify the fix
Confirm the value is now correct:
odmget -q "name=<object> and attribute=<attribute>" CuAtIf applicable, confirm at the operating system level as well (e.g. for hostname):
hostname
uname -nRe-run a manual backup to confirm the XML file now generates successfully:
viosbr -backup -file /home/padmin/<test_filename>Once confirmed clean, re-enable or re-run the scheduled HMC backup for this VIOS to confirm it completes successfully going forward.
Additional Information
- If your organization maintains a separate inventory or CMDB system that tracks VIOS configuration details, that system may need a manual refresh or re-sync to reflect the corrected value — this is independent of the fix applied on the VIOS itself and depends on how your CMDB sources its data.
- This type of issue can exist quietly for a long time before it's discovered, since it only surfaces the next time a backup is attempted. It does not indicate a recent problem or anything wrong with recent changes.
- This same troubleshooting approach applies generally to any `viosbr` "Backup XML file is not well formed" error, regardless of which specific configuration item is involved — the process is to identify the invalid data, trace it to the affected value, correct it through the proper supported command, and verify the backup completes cleanly.
| SUPPORT |
|---|
If you require more assistance, use the following step-by-step instructions to contact IBM to open a case for software with an active and valid support contract. 1. Document (or collect screen captures of) all symptoms, errors, and messages related to your issue. 2. Capture any logs or data relevant to the situation. 3. Contact IBM to open a case: -For electronic support, see the IBM Support Community: 4. Provide a clear, concise description of the issue. - For more information, see: Working with IBM AIX Support: Describing the problem. 5. If the system is accessible, collect a system snap, and upload all of the details and data for your case. - For more information, see: Working with IBM AIX Support: Collecting snap data |
Document Location
Worldwide
Was this topic helpful?
Document Information
Modified date:
31 July 2026
UID
ibm17282210