Update AWS.DomainJoin.exe.config to resolve unhandled exception on Windows domain join

[burck1]

Description of changes:

This update resolves an error we are seeing when attempting to join a Windows EC2 instance to our Active Directory domain.

The error can be seen when running the AWS-JoinDirectoryServiceDomain or AWS-JoinDirectoryServiceDomain-V2 documents, or when running a custom document that uses the aws:domainJoin action.

The stderr output is

Unhandled Exception: System.IO.FileLoadException: Mixed mode assembly is built against version 'v2.0.50727' of the runtime and cannot be loaded in the 4.0 runtime without additional configuration information.
exit status 1

Additionally, the error can be replicated by running the AWS.DomainJoin.exe directly.

PS C:\Program Files\Amazon\SSM\Plugins\awsDomainJoin> ls AWS.DomainJoin.*


    Directory: C:\Program Files\Amazon\SSM\Plugins\awsDomainJoin


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----         1/10/2025   1:10 AM          58000 AWS.DomainJoin.exe
-a----         1/10/2025   1:05 AM           1927 AWS.DomainJoin.exe.config


PS C:\Program Files\Amazon\SSM\Plugins\awsDomainJoin> .\AWS.DomainJoin.exe

Unhandled Exception: System.IO.FileLoadException: Mixed mode assembly is built against version 'v2.0.50727' of the runtime and cannot be loaded in the 4.0 runtime without additional configuration information.

PS C:\Program Files\Amazon\SSM\Plugins\awsDomainJoin> $LASTEXITCODE
-532462766

The solution to add useLegacyV2RuntimeActivationPolicy="true" was recommended in this stack overflow post and confirmed in the documentation.

Additionally, I have tested the solution by updating the AWS.DomainJoin.exe.config file to include the useLegacyV2RuntimeActivationPolicy="true" property and then re-running the exe and SSM document.

PS C:\Program Files\Amazon\SSM\Plugins\awsDomainJoin> cat .\AWS.DomainJoin.exe.config -Head 5
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <startup useLegacyV2RuntimeActivationPolicy="true">
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0,Profile=Client" />
    <supportedRuntime version="v2.0.50727" />

PS C:\Program Files\Amazon\SSM\Plugins\awsDomainJoin> .\AWS.DomainJoin.exe
Domain join failed with exception: Domain Join failed

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[burck1]

Hi @Aperocky, @gianniLesl, @rhaoran-aws, @andrei-a2, @bryantbiggs. Apologies, just tagging a few recent contributors to this repo. Can you point me to the right person to get this PR reviewed and merged? Is there anything you need from me to proceed?

[rhaoran-aws]

Thanks @burck1 for submitting this PR

Could you please share on which SSM Agent version and OS version you were facing this issue? Steps to reproduce would be even better

[burck1]

Hi Haoran. We have seen this issue occur on all of the latest Windows_Server-2016-English-Core-Base-* and Windows_Server-2025-English-Core-Base-* AMIs. We haven't had a chance to test out server 2019 / server 2022. Looks like the latest OS is Windows Server 2025 Datacenter and SSM Agent version 3.3.1611.0.

Steps to reproduce would be even better

We think we have narrowed this issue down to occuring only when our our antivirus solution is installed before attempting to domain join the instance. We use a tool called Carbon Black Cloud. We have observed that if we launch the latest windows server AMI, install Carbon Black, reboot, then attempt to run the AWS-JoinDirectoryServiceDomain SSM document or attempt to run the AWS.DomainJoin.exe directly, we see the reported error. But if we instead first apply the fix in this PR, the domain join process succeeds with and without Carbon Black installed.

Unfortunately we cannot provide you with the MSI installer for Carbon Black and they do not provide a public download for the MSI, so it may be difficult for you to re-create the issue unless you have access to a Carbon Black Cloud account.

---

We've created a temporary workaround for the issue. We build custom AMIs, so we now run the following PowerShell script during our AMI build process to apply the change in this PR in our custom AMIs:

$configPath = Join-Path $env:ProgramFiles 'Amazon\SSM\Plugins\awsDomainJoin\AWS.DomainJoin.exe.config'
if (-not (Test-Path $configPath))
{
    throw 'AWS.DomainJoin.exe.config not found'
}

Write-Host 'Reading AWS.DomainJoin.exe.config'
$config = Get-Content $configPath -Raw

$findString = '<startup>'
$replacementString = '<startup useLegacyV2RuntimeActivationPolicy="true">'

if ($config.Contains($replacementString))
{
    Write-Host 'AWS.DomainJoin.exe.config is already updated. Skipping...'
    return
}

if (-not $config.Contains($findString))
{
    throw "$findString not found in AWS.DomainJoin.exe.config"
}

$updatedConfig = $config.Replace($findString, $replacementString)

Write-Host 'Updating AWS.DomainJoin.exe.config'
Set-Content $configPath -Value $updatedConfig -Encoding 'UTF8' -NoNewline -Force
Write-Host 'Updated AWS.DomainJoin.exe.config'

[burck1]

Hi @rhaoran-aws. Do you have any questions for me? Is there anything you need from me to get this update merged?