Troubleshooting

Capture A Structured Error Log

Add -ErrorLogPath to the failing plan, WhatIf, or deployment command:

New-AzureSqlVmToolkitDeployment `
  -ConfigFile .\config.local.yaml `
  -WhatIf `
  -ErrorLogPath .\test-results\errors\deployment.jsonl

The file is created only for a terminating failure. Inspect its run ID, phase, resource context, and Azure correlation ID:

Get-Content .\test-results\errors\deployment.jsonl |
  ForEach-Object { $_ | ConvertFrom-Json } |
  Select-Object timestampUtc, runId, mode, phase, azureCorrelationId

Known secret formats are redacted, but exception text can come from external providers. Review the file before sharing it and keep it out of source control. If logging itself fails, the warning describes the logging problem while the original deployment error remains the terminating error.

Missing powershell-yaml

Install it:

Install-Module -Name powershell-yaml -Scope CurrentUser -Force

No Azure Context

Real deployment requires:

Connect-AzAccount

-Plan does not require Azure sign-in.

Missing VM Password Secret

Create the secret in Key Vault before deploying, or use -GeneratePassword for a disposable lab.

Legacy Key Vault Access Policies

The script rejects existing Key Vaults that do not use RBAC authorization. Use a different vault name or migrate the vault.

Broad RDP Or SQL Rule Rejected

Validation rejects inbound 3389 and 1433 from broad sources. Keep Bastion-only access or restrict the source prefix.

Local Checks

Run:

.\scripts\Test-Local.ps1 -ConfigFile .\config.local.yaml