(2025.12.01 and earlier) Windows 11 virtual desktops fail to launch due to missing registry keys

Windows 11 virtual desktops fail to launch because the bootstrap process attempts to set a registry key (HKLM:\SOFTWARE\Microsoft\Active Setup\Installed Components\{A509B1A7-37EF-4b3f-8CFC-4F3A74704073}) that does not exist on Windows 11. The Set-ItemProperty PowerShell command fails with a non-zero exit status, causing the VDI app to crash during initialization.

2025.12.01 and earlier

1. Download patch.py and win11-bootstrap-registry-fix-{version}.patch for version 2025.06, 2025.06.01, or 2025.09 by replacing <output-directory> with the directory to download the patch script, <res-version> with the RES version you have deployed, and patch file and <environment-name> with the name of your RES environment in the command below:
   1. The patch applies to RES 2025.06, 2025.06.01, or 2025.09
   2. The patch script requires AWS CLI v2, Python 3.9.16, and Boto3.
   3. Configure the AWS CLI for the account / region where RES is deployed, and make sure that you have S3 permissions to write to the bucket created by RES.

OUTPUT_DIRECTORY=<output-directory>
ENVIRONMENT_NAME=<environment-name>
RES_VERSION=<res-version> # e.g. 2025.06, 2025.06.01, or 2025.09

mkdir -p ${OUTPUT_DIRECTORY}
curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/${RES_VERSION}/patch_scripts/patch.py --output ${OUTPUT_DIRECTORY}/patch.py
curl https://research-engineering-studio-us-east-1.s3.amazonaws.com/releases/${RES_VERSION}/patch_scripts/patches/win11-bootstrap-registry-fix-${RES_VERSION}.patch --output ${OUTPUT_DIRECTORY}/win11-bootstrap-registry-fix-${RES_VERSION}.patch

2. Navigate to the directory where the patch script and patch file are downloaded. Run the following patch command:

python3 ${OUTPUT_DIRECTORY}/patch.py --environment-name ${ENVIRONMENT_NAME} --res-version ${RES_VERSION} --module virtual-desktop --patch ${OUTPUT_DIRECTORY}/win11-bootstrap-registry-fix-${RES_VERSION}.patch

3. Launch a new Windows 11 VDI to use the updated package.

1. Create an S3 bucket with ACLs disabled.
2. Download patch_host.py and idea-virtual-desktop-{res-version}-<HASH>.tar.gz by replacing <output-directory> with the directory to download the patch script, <environment-name> with the name of your RES environment, <bucket-name> with the name of a ACLs disabled S3 bucket under the account/region where RES is deployed, RES_VERSION with 2025.12 or 2025.12.01, and <partition> with Classic or GovCloud in the command below:
   1. The patch applies to 2025.12, 2025.12.01
   2. The patch script requires AWS CLI v2, Python 3.9.16 or above, and Boto3.
   3. Configure the AWS CLI for the account / region where RES is deployed, and make sure that you have S3 permissions to write to the bucket provided through <bucket-name>.

OUTPUT_DIRECTORY=<output-directory>
ENVIRONMENT_NAME=<environment-name>
RES_VERSION=<RES_VERSION>
BUCKET_NAME=<bucket-name>
PARTITION=<partition>

mkdir -p ${OUTPUT_DIRECTORY}
HASH=$(case $RES_VERSION in "2025.12.01") echo 233fddcc;; "2025.12") echo 6e64f380;; esac)
curl https://research-engineering-studio-us-east-1.s3.us-east-1.amazonaws.com/releases/${RES_VERSION}/patch_scripts/patch_host.py --output ${OUTPUT_DIRECTORY}/patch_host.py
curl https://research-engineering-studio-us-east-1.s3.us-east-1.amazonaws.com/releases/${RES_VERSION}/patch_scripts/patches/idea-virtual-desktop-${RES_VERSION}-${HASH}.tar.gz --output ${OUTPUT_DIRECTORY}/idea-virtual-desktop-${RES_VERSION}-${HASH}.tar.gz

3. Run the following patch command:

python3 ${OUTPUT_DIRECTORY}/patch_host.py --environment-name ${ENVIRONMENT_NAME} --module virtual-desktop --zip-file ${OUTPUT_DIRECTORY}/idea-virtual-desktop-${RES_VERSION}-${HASH}.tar.gz --s3-bucket ${BUCKET_NAME} --partition ${PARTITION}

4. Launch a new Windows 11 VDI to use the updated package.

For 2025.09 and earlier:

1. Re-run patch.py with the same patch file, it will unpatch the environment (the script toggles the patch).
2. Launch a new Windows 11 VDI to pick up the restored URI.

For 2025.12 and 2025.12.01: The patch modified the DynamoDB *.app_package_uri record to point to the patched tar.gz. To rollback:

1. Restore the original value:

ENVIRONMENT_NAME=<environment-name>
RES_VERSION=<res-version>  # 2025.12 or 2025.12.01
REGION=<region>  # e.g. us-east-1

aws dynamodb update-item \
    --table-name ${ENVIRONMENT_NAME}.cluster-settings \
    --key '{"key": {"S": "vdi-app.app_package_uri"}}' \
    --update-expression "SET #val = :val" \
    --expression-attribute-names '{"#val": "value"}' \
    --expression-attribute-values "{\":val\": {\"S\": \"s3://research-engineering-studio-${REGION}/releases/${RES_VERSION}/idea-virtual-desktop-${RES_VERSION}.tar.gz\"}}"

2. Launch a new Windows 11 VDI to pick up the restored URI.