Test-TargetResource throws unhandled exception instead of returning $false (Azure Arc Guest Configuration failure)

[manuelgr0]

Problem description

I am using Azure Arc Guest Configuration to manage SQL Server settings. This issue appears to be systemic across multiple resources in this module (e.g., SqlConfiguration, SqlDatabaseMail, and others).

When the Guest Configuration agent runs a consistency check, it executes Test-TargetResource. Most resources in this module implement Test- by calling Get-TargetResource, which internally calls Connect-SQL.

If the target SQL Server instance is not yet installed, the service is stopped, or the instance is unreachable, the Connect-SQL helper function throws a terminating error (e.g., SQLCOMMON0019).

Because Test-TargetResource does not catch this exception in many resources, the Guest Configuration agent reports a DscConfigurationExecutionFailed error and marks the resource as non-compliant with a fatal error.

Consequence:
Since the Test method crashes, the Guest Configuration agent never attempts to run Set-TargetResource. This prevents the configuration from ever applying or self-correcting (remediating), even if the policy is set to ApplyAndAutoCorrect.

Expected Behavior:
If Test-TargetResource cannot connect to the SQL instance (e.g., because it doesn't exist yet), it should catch the exception, log a verbose message, and simply return $false. This would allow the Guest Configuration agent to proceed to Set-TargetResource to install or configure the instance.

Actual Behavior:
The resources throw unhandled exceptions, causing the entire Guest Configuration policy application to fail.

Verbose logs

DscConfigurationExecutionFailed

PowerShell DSC resource DSC_SqlConfiguration failed to execute Test-TargetResource functionality with error message: The running command stopped because the preference variable "ErrorActionPreference" or common parameter is set to Stop: Failed to connect to SQL instance 'SQLSERVER\T99'. (SQLCOMMON0019)

DSC configuration

Configuration ReproExample
{
    Import-DscResource -ModuleName SqlServerDsc

    Node localhost
    {
        # This issue affects multiple resources.
        # Example 1: SqlConfiguration
        SqlConfiguration 'ExampleConfig'
        {
            InstanceName = 'MSSQLSERVER'
            OptionName   = 'Max server memory (MB)'
            OptionValue  = 2048
        }

        # Example 2: SqlDatabaseMail
        SqlDatabaseMail 'ExampleMail'
        {
            InstanceName   = 'MSSQLSERVER'
            AccountName    = 'TestAccount'
            EmailAddress   = 'test@contoso.com'
            MailServerName = 'smtp.contoso.com'
            ProfileName    = 'TestProfile'
        }
    }
}

Suggested solution

The Test-TargetResource function in these resources usually calls Get-TargetResource to retrieve the current state. This call should be wrapped in a try...catch block across all affected resources.

If an exception occurs during the "Get" phase (specifically connection errors), Test-TargetResource should swallow the error and return $false.

General fix pattern:

function Test-TargetResource
{
    # ... params ...

    try
    {
        # Attempt to get current state
        $getTargetResourceResult = Get-TargetResource @PSBoundParameters -ErrorAction Stop
    }
    catch
    {
        # If we can't connect, we aren't in the desired state. 
        # Return $false so Set-TargetResource can run.
        Write-Verbose -Message "Test-TargetResource: Unable to connect to SQL instance. Assuming resource is not in desired state. Error: $_"
        return $false
    }

    # ... existing comparison logic ...
}

### SQL Server edition and version

```text
2022

SQL Server PowerShell modules

22.4.5.1

Operating system

Windows Server 2022

PowerShell version

7

SqlServerDsc version

17.5.0

[johlju]

But the resource instances in the configuration should be dependent on the install resource instance. Are you saying GC does not handle this but LCM does?

[manuelgr0]

Unfortunately, GC handles things differently and I'm not sure if that is something I should tell Microsoft with a support ticket or if we should fix it in the Module.

The guest configuration agent runs all the Test-TargetResource of all the resources in one configuration. It does not care about the DependsOn statements. If even one of the resources throws an error, it will just display this:

DscConfigurationExecutionFailed

PowerShell DSC resource DSC_SqlConfiguration failed to execute Test-TargetResource functionality with error message: 
The running command stopped because the preference variable "ErrorActionPreference" or common parameter is set to Stop: Failed to connect to SQL instance 'SQLSERVER\T99'. (SQLCOMMON0019)

See the DscConfigurationExecutionFailed?

Unfortunately, it gets worse. If the Test-TargetResource fails, it won't trigger the remediation. This means that the Guest Configuration package will not call the Set-TargetResource.

This means that if you have SqlSetup with another dependent resource in the same configuration, it will not ever work on a fresh server.

Microsoft also confirmed that there is currently no way on making Guest Configuration packages dependent on each other. This means that we are required to pack all the resources in one big package/configuration.

@johlju What do you think about this?

[manuelgr0]

Unfortunately, the same is true for the Get-TargetResource. I opened a support ticket with Microsoft and will update this issue as soon as I get an answer.

[johlju]

You can't make the resources dependent on each other in the package/configuration like the LCM supports?

The root cause seems to that GC runs resources if not all dependency is in place.

Removing that the resources to not throw will not surface errors where for example a SQL instance is down and it would try to set the configuration forever regardless. It would also fail to surface the expected error if the user just runs Get and and SQL instance is not available.

[manuelgr0]

Just a quick update following a call with Microsoft Support, where they clarified how Guest Configuration handles exceptions.

When evaluating a DSC Configuration with multiple resources (e.g., SqlSetup and SqlConfiguration), the system first calls the Test-TargetResource and Get-TargetResource functions for all resources to check compliance. A DependsOn statement does not change this behavior during the evaluation phase.

Crucially, if an exception occurs during any of these function calls, the entire Guest Configuration execution is aborted. As a result, the remediation step will not be triggered for any of the resources.

Unfortunately, I won't have the capacity to work on a fix for this in the near future, so we will be implementing a workaround on our side for the time being.

[github-actions]

This issue has been automatically marked as stale because it has not had activity from the community in the last 30 days. It will be closed if no further activity occurs within 40 days. If the issue is labelled with any of the work labels (e.g bug, enhancement, documentation, or tests) then the issue will not auto-close.