Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

OVF or OVA deploy fails: certificate, manifest and network mapping errors

Technical article
VMware

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

An OVF package is a descriptor (.ovf), its disks (.vmdk), and optionally a manifest (.mf) of file hashes and a signing certificate (.cert). An OVA is the same files in one archive. When a deploy fails, the message nearly always names one of four things. The signing certificate is untrusted or expired ("The Certificate is not trusted", "The Certificate is Expired"). The manifest does not match the files ("The checksum(s) from the provided manifest file do not match", "Unable to retrieve manifest or certificate file"). The descriptor is wrong for this host ("No supported hardware versions", "PARSE_ERROR"). Or a network the template expects does not exist ("Host did not have any virtual network defined"; in a new VMware Cloud Foundation deployment, "Invalid target name ... specified in net mapping"). Match the message, prove it, and fix that one thing.

What the error means

TechDocs: "The vSphere Client validates an OVF or OVA file before importing it, and ensures that it is compatible with the intended destination server. If the appliance is incompatible with the selected host, it cannot be imported and an error message appears."

Certificate checks became stricter in vCenter 7.0 Update 2. KB 336085: "Starting 7.0 U2, the OVF signing certificates are verified for their expiry, validity and checked if the signing certificate is trusted. This means that the entire chain of the signing certificate should be trusted against the VECS store." The OVF Tool guide describes what signing needs: "a manifest (.mf) file that contains the SHA hash codes of all the files in the package (except the .mf and .cert files), and a certificate file (.cert) that contains the signed SHA of the manifest file and the X.509 encoded certificate." Change any file in the package and its hash no longer matches the manifest.

Networks are symbolic names inside the descriptor. On the wizard's Select networks page, "The Source Network column lists all networks that are defined in the OVF or OVA template." Each must be mapped to a port group that exists on the target host.

Likely causes

Cause What you see Source
Signing chain not trusted by vCenter "The Certificate is not trusted" KB 336085
Signing certificate expired "The Certificate is Expired" (content library import) KB 435205
File changed after the manifest was made "The checksum(s) from the provided manifest file do not match the content of file(s)" KB 406641
Manifest read too late with large disks "Unable to retrieve manifest or certificate file." KB 425836
OVA from a URL on older vCenter "Unable to retrieve manifest or certificate file" KB 318572
.cert uploaded without .mf (8.0U3 and later) file_in_wrong_order_error KB 447962
Hidden byte order mark in the .ovf "PARSE_ERROR: Parse error: Unexpected character ''" KB 446664
Hardware version newer than the host supports "No supported hardware versions among [vmx-21]" KB 315994
Template expects a port group that does not exist "Host did not have any virtual network defined" KB 328836
New VCF deployment: no port group named "VM Network" on the destination host VCF Installer "vCenter installation failed"; ci-installer.log: "Invalid target name (VM Network) specified in net mapping" KB 396267
Stale content library session "Unable to process template." KB 449655

Prove the cause before changing anything

These steps only read.

1. Copy the exact message from the wizard or the failed task, including any file name.

2. Read the logs on vCenter. Manifest, certificate and checksum errors appear in /var/log/vmware/content-library/cls.log. KB 425836's line contains transfer_failed_mf_cert_retrieval_timeout; KB 406641's contains invalid_manifest_checksum_mismatch and names the file that does not match. For "Unable to process template.", KB 449655 shows Unable to query OVF. com.vmware.vapi.std.errors.Unauthorized: Unauthorized in /var/log/vmware/vsphere-ui/logs/vsphere_client_virgo.log.

3. Look inside the package. List an OVA's contents with tar -tvf (KB 318572 extracts one with tar -xvf Filename.ova). Check whether a .mf and .cert are present, and in the .ovf find the <vssd:VirtualSystemType> line and the network names. For a suspected byte order mark, KB 446664 runs # file template.ovf; a bad file reports "UTF-8 Unicode (with BOM) text".

For a suspected checksum mismatch, compare a hash yourself; this only reads. Open the .mf in a text editor: it lists each file name with its hash, and KB 406641 says the checksum is "typically a hash value, like MD5 or SHA256". Calculate the same algorithm for the file the error names, then compare the two strings. KB 446664 uses Get-FileHash in PowerShell; KB 406641 uses the 7-Zip right-click menu "CRC SHA". On Linux, sha256sum <file> gives the SHA-256 value. If your calculated value differs from the .mf line, the file is not the one the manifest describes.

4. Check the certificate. The wizard's review page shows "Publisher of the OVF or OVA template, if a certificate included in the OVF or OVA template file specifies a publisher." A not-trusted warning with a known publisher points to a missing root or intermediate in vCenter's trusted roots. An expired one points to KB 435205.

5. Compare networks and hardware with the host. The descriptor's network names must exist as port groups on the target host. The hardware version must be in the "supported" list the error prints.

Example (illustrative): an appliance OVA deploys on one vCenter 8.0 but fails on another with "The Certificate is not trusted". The review page names the vendor as publisher. Under Administration > Certificates > Certificate Management, the second vCenter lacks the vendor's intermediate certificate that the first one has. The cause is KB 336085's alone.

Fix

Signing chain not trusted. KB 336085: get the signing certificate's root and intermediates, then in the vSphere Client select "administration -> Certificates -> Certificate Management", click "ADD" next to Trusted Roots Certificates and add them. You can instead click "Ignore" next to the warning for one deploy. Risk: adding a root makes vCenter trust everything that root signs; add only the vendor's real chain.

Certificate expired. KB 435205: "The Signing Certificate used for signing the currently available OVFs during the import process is expired." "Broadcom engineering is actively working on a fix in a future 9.x release." Ask the vendor for a re-signed package.

Checksum mismatch. KB 406641 workaround 1: "Extract the OVA file and use the .ovf and .vmdk files to deploy the OVA." Workaround 2 recalculates the SHA with 7-Zip's "CRC SHA" menu and edits the manifest. Risk: a mismatch can mean a corrupt or altered download; download the package again from the vendor before overriding the check.

Manifest read too late (large disks). KB 425836 Option B edits /etc/vmware-content-library/config/ts-config.properties, changing transfer.http.request.timeout.seconds=120 and transfer.nfcClient.socket.timeout.seconds=120 to 240; Option A raises transfer.threads.poolSize=20. Then service-control --restart vmware-content-library. Disruptive step: "offline snapshots of all ELM nodes are required" for linked vCenters; the restart ends running library tasks.

OVA from a URL. KB 318572: "This issue is resolved in VMware vCenter Server version 8.0 U1." Workarounds: "Deploy the OVA from a local file", or extract it and "Deploy the OVF file from the URL." TechDocs: "Verify that all files from the OVF package are at the same location of the OVF descriptor file."

file_in_wrong_order_error. KB 447962 "Method 1: Include All Signature Files": upload ".ovf, .vmdk (all disks), .mf, and .cert." Method 2 uploads unsigned, excluding "Both the .mf and .cert files." "Method 1 is recommended".

Byte order mark. KB 446664: save the .ovf as UTF-8 "not "UTF-8 with BOM"" in a code editor. The change alters its hash, "which will cause a manifest mismatch error"; either delete the .mf or recalculate the SHA-256 "(using Get-FileHash in PowerShell)" and update it ("Recommended for security"). Delete the failed library item and re-import.

Hardware version. KB 315994 (written for vCenter 7.x): convert the OVA to OVF with ovftool, back up the .ovf, change <vssd:VirtualSystemType>vmx-21</vssd:VirtualSystemType> to a supported version such as vmx-19, and retry. Risk: the guest may rely on newer virtual hardware; ask the vendor whether the lower version is supported, or deploy to a host that supports vmx-21. The edit also breaks the manifest as above.

Missing network. KB 328836 creates a port group named "VM Network" (Configure > Networking > Virtual Switches > ADD NETWORKING) or edits the .ovf network labels. Mapping the source network to an existing port group on the Select networks page avoids editing files. With OVF Tool, map names explicitly: --net:<OVFname>=<target name>, repeated for each network, or --network "when only one network exists in the OVF package". KB 340425 shows the full form for a host deployment: --network="PortGroup", then the package path, then a vi:// target such as vi://<user>@<esxi-host>.

VMware Cloud Foundation installer. KB 396267 covers one case of the "Invalid target name (VM Network) specified in net mapping" error: a new greenfield VCF deployment, where "The VCF Installer expects the virtual machine portgroup on ESX to be "VM Network"". Its steps: on the destination ESX host UI, go to Networking > Port groups, "Ensure a port group named "VM Network" exists, or modify the deployment configuration parameters to match a valid, existing port group on the host", then retry. This is an installer setting, not an OVF Tool usage fault, and the KB is written for VCF Operations 9.x.

Unable to process template. KB 449655: service-control --restart vmware-content-library vsphere-ui, "Wait approximately 2–3 minutes", log in again and retry. Disruptive step: users lose their vSphere Client session.

OVF Tool strict checks. KB 432820, written for VMware Cloud Director 10.x, Telco Cloud Platform and ESXi, covers an OVF Tool deployment that fails with Unsupported value 'XXXXX' for attribute 'key' on element 'ExtraConfig'. It adds --allowExtraConfig and --skipManifestCheck. Risk: the OVF Tool guide calls ExtraConfig options "a security risk as they control low-level and potentially unsafe options on the VM"; use only for a package you trust.

Confirm the fix

  • The wizard passes compatibility checks and the review page shows the expected publisher.
  • The deploy task completes; cls.log shows no new manifest or certificate errors.
  • The VM's network adapters are on the intended port groups and it gets an address.
  • The VM's hardware version matches what you chose.

What to watch afterwards

  • Vendor certificates. Note expiry dates of appliance signing certificates you rely on.
  • Edited packages. Keep the original vendor files; record any descriptor edit.
  • Port group names that templates and installers expect, such as "VM Network".
  • Large disks imported through content libraries, and the timeouts above.

Risks and limits

  • Skipping manifest or certificate checks removes the protection against corrupt or altered packages.
  • KB 315994 lists vCenter 7.x and KB 336085 lists 7.0.x; check that a fix applies to your vCenter version first.
  • Product installers (NSX, HCX, VCF) have their own mapping errors and KBs.

NetLeverage runs its own hosting on VMware vSphere, vCenter and ESXi. Talk to an engineer.

Sources