[Bug]: New-VM fails with "Value cannot be null. (Parameter 'HostId')" on single-host vCenter cluster during ESX build

Holorouter Version

9.1

VCF Version

VCF 9.0.2.0

Target Type

vCenter Cluster

Describe the bug

On a single-ESX-host vCenter cluster, New-HoloDeckInstance fails during the ESX build phase (ESXiBuild.psm1, New-HoloDeckESXi) with:

New-VM: Value cannot be null. (Parameter 'HostId')

All ESX VM build jobs fail with this error, followed by a Get-VM ... was not found error in the reconfigure phase, and the deployment aborts.

Root cause: ESXiBuild.psm1 builds the New-VM splat using a bare-string -ResourcePool (from $config.target.resourcePool, falling back to $config.target.Cluster if empty) combined with a -PortGroup parameter (a resolved VirtualPortGroupImpl object). In a single-host cluster, this exact combination causes PowerCLI's New-VM to fail resolving a HostId internally, even though every individual parameter value is independently valid and resolvable. Confirmed via manual reproduction outside Holodeck's script (see Reproduction steps).

This could be related to #138 ("Portgroup not accessible from this host") in that both fail inside New-HoloDeckESXi at the same New-VM call (ESXiBuild.psm1 line 358) when a PortGroup is involved. However the failure mode, environment, and apparent root cause differ: #138 is a 4-node NSX-backed cluster hitting a genuine reachability VimException, while this is a single-host vSS-backed cluster hitting a null-parameter binding failure regardless of actual reachability. Flagging both in case there's a shared underlying fragility in how this call resolves host/network placement.

Reproduction steps

1. Deploy Holorouter 9.1 against a single-host vCenter-managed cluster with a standard vSwitch trunk port group (VLAN 4095, Promiscuous Mode / MAC Address Changes / Forged Transmits set to Accept).
2. Complete prechecks (datastore, trunk port group) — note datacenter/cluster are not prompted for in this topology and must be set manually on $config.Target.datacenter / $config.Target.cluster / $config.Target.resourcePool.
3. Run New-HoloDeckInstance -Version 9.0.0.0 -InstanceID test -ManagementOnly ...
4. Deployment fails at ESX build with the null HostId error on every ESX VM build job.

Minimal manual reproduction, outside Holodeck entirely, same vCenter session:

# Fails — reproduces the exact error:
$newVMParams = @{
    Name              = "test-vm"
    ResourcePool      = "holodeck"          # bare string, resolves fine via Get-ResourcePool
    Datastore         = "datastore1"
    Numcpu            = 1
    MemoryGB          = 1
    DiskGB            = 1
    DiskStorageFormat = 'Thin'
    PortGroup         = (Get-VirtualPortGroup -Name "Holodeck")   # resolves fine independently
    RunAsync          = $true
}
New-VM @newVMParams
# New-VM: Value cannot be null. (Parameter 'HostId')

# Succeeds — identical params, PortGroup omitted:
$newVMParams2 = @{
    Name              = "test-vm2"
    ResourcePool      = "holodeck"
    Datastore         = "datastore1"
    Numcpu            = 1
    MemoryGB          = 1
    DiskGB            = 1
    DiskStorageFormat = 'Thin'
    RunAsync          = $true
}
New-VM @newVMParams2
# Succeeds, CreateVM_Task starts normally

Ruled out while isolating this: config values for cluster/datacenter/resourcePool/portgroup all resolve correctly and independently via manual PowerCLI calls; single, clean $global:DefaultVIServers connection at time of failure; DefaultVIServerMode set to Single; module freshly reloaded (Remove-Module/Import-Module -Force) to rule out stale cached code from earlier edits.

Expected behavior

New-HoloDeckInstance successfully creates the nested ESX host VMs on a single-host vCenter cluster, the same as it does on multi-host clusters.

Relevant logs

11-09-2026 14:10:53  ESXBuild[1124357]: [INFO] Deploy ESX for management
11-09-2026 14:10:53  ESXBuild[1124357]: [INFO] Target API Type is VirtualCenter
11-09-2026 14:10:53  ESXBuild[1124357]: [INFO] Validating existing VMs in Host/VirtualCenter inventory...
11-09-2026 14:10:53  ESXBuild[1124357]: [INFO] Initiating VM Build Job for tanzuvcf-esx-01a
New-VM: 9/11/2026 2:10:52 PM New-VM  Value cannot be null. (Parameter 'HostId')
...
11-09-2026 14:10:54  ESXBuild[1124357]: [INFO] Reconfiguring tanzuvcf-esx-01a
Get-VM: 9/11/2026 2:10:54 PM Get-VM  VM with name 'tanzuvcf-esx-01a' was not found using the specified filter(s).
11-09-2026 14:10:54  ESXBuild[1124357]: [ERROR] Site Deployment failed.
11-09-2026 14:10:54  ESXBuild[1124357]: [ERROR] You cannot call a method on a null-valued expression.
11-09-2026 14:10:54  ESXBuild[1124357]: [ERROR] HoloDeck deployment failed.

=== FULL ERROR DIAGNOSTICS (DEPLOYMENT FAILED) ===
--- Error [3]  ---
Message: 9/11/2026 2:18:15 PM	New-VM		Value cannot be null. (Parameter 'HostId')
Exception Type: VMware.VimAutomation.Sdk.Types.V1.ErrorHandling.VimException.VimException
Script: /root/.local/share/powershell/Modules/HoloDeck/Modules/ESXiBuild.psm1
Line: 358
Stack Trace:
at New-HoloDeckESXi<Process>, /root/.local/share/powershell/Modules/HoloDeck/Modules/ESXiBuild.psm1: line 358
at New-HoloDeckESXiNodes<Process>, /root/.local/share/powershell/Modules/HoloDeck/Modules/ESXiBuild.psm1: line 615
at New-HoloSite<Process>, /root/.local/share/powershell/Modules/HoloDeck/Modules/HoloSite.psm1: line 61
at New-HoloDeckInstance<Process>, /root/.local/share/powershell/Modules/HoloDeck/HoloDeck.psm1: line 1125
Inner Exception: Value cannot be null. (Parameter 'HostId')

Additional context

Workaround confirmed working: resolve an explicit -VMHost and add it to the New-VM splat in ESXiBuild.psm1, right after $deploymentTarget is set (~line 339):

$vmHost = Get-VMHost -Location $deploymentTarget -ErrorAction SilentlyContinue | Select-Object -First 1
if (-not $vmHost) { $vmHost = Get-VMHost -Location $config.target.Cluster | Select-Object -First 1 }

Then add VMHost = $vmHost as a key in the $newVMParams hashtable (~line 347), alongside ResourcePool, Datastore, PortGroup, etc. With this change, ESX VMs build successfully on the single-host cluster.

This appears to intersect with a known-flaky area of PowerCLI's New-VM around network/host resolution — community reports going back to PowerCLI 11.2 describe similar null-parameter failures tied to -PortGroup (VMware Communities: "New-VM in 11.2 requires a portgroup"). This exact combination (bare-string ResourcePool + PortGroup object + single-host cluster → null HostId) doesn't appear previously documented and seems specific to single-host clusters, where PowerCLI apparently lacks enough placement context to resolve on its own.