diff --git a/docs/troubleshooting/known-issues.md b/docs/troubleshooting/known-issues.md new file mode 100644 index 000000000..c0b6817a9 --- /dev/null +++ b/docs/troubleshooting/known-issues.md @@ -0,0 +1,160 @@ +--- +title: 'Known issues: Microsoft Desired State Configuration' +description: "Troubleshooting and known issues for Microsoft Desired State Configuration (DSC)." +author: michaeltlombardi +ms.author: mlombardi +ms.service: dsc +ms.topic: troubleshooting-known-issue +ms.date: 07/14/2025 +--- + +# Known issues: Microsoft Desired State Configuration + +This article lists known issues and troubleshooting guidance for Microsoft Desired State Configuration (DSC). + +The following table lists known issues with Microsoft DSC v3: + +| Issue | Description | Status | Reported on | +|:--------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------|:---------:|:------------:| +| [Unable to parse content from ``](#t01) | When authoring a resource manifest in VS Code, you may encounter parsing errors. | Confirmed | [#917][#917] | +| [Resource not found when using Windows PowerShell adapter](#t02) | A resource can't be found when using the `Microsoft.Windows/WindowsPowerShell` adapter. | Confirmed | [#765][#765] | +| [Validation errors when executing dsc.exe in Windows PowerShell sessions](#t03) | DSC raises input validation errors when invoked in Windows PowerShell | Confirmed | [#965][#965] | + +For the most up-to-date information on known issues, see the [DSC GitHub repository issues][01]. + +## Unable to parse content from `` + + + +When authoring a resource manifest in Visual Studio Code (VS Code), you may encounter a parsing error: + +> Unable to parse content from `` + +This error occurs because canonical schema bundling isn't fully supported in VS Code. Canonical +schema bundling was introduced with the 2020-12 JSON schema specification. + +### Prerequisites + +- Visual Studio Code +- Microsoft DSC v3.0 or later + +### Troubleshooting steps + +To resolve this issue, use `manifest.vscode.json` in the schema URI for your resource manifest. +This enables enhanced authoring support in VS Code. + +For more information, see [Enhanced authoring][02]. + +### Possible causes + +- The resource manifest references a schema that isn't compatible with the VS Code JSON schema parser. +- VS Code doesn't currently support parsing canonically bundled schemas. + +## Resource not found when using Windows PowerShell adapter + + + +When running DSC configurations with the `Microsoft.Windows/WindowsPowerShell` adapter, you may +encounter errors indicating that a required resource cannot be found. + +### Prerequisites + +- Windows PowerShell DSC (PSDSC) 1.1 (included with Windows) +- Using the `Microsoft.Windows/WindowsPowerShell` adapter in a configuration document or to + directly invoke a resource + +### Issue description + +The [Microsoft.Windows/WindowsPowerShell][03] adapter relies on PSDSC 1.1, which uses the Local +Configuration Manager (LCM) running as a Windows service. By design, the LCM service only accesses +resources installed in the **AllUsers** scope under the Program Files directory. If a PSDSC module +is installed for the current user only, the service cannot detect or use it, resulting in a +"resource not found" error. + +This limitation is specific to the `Microsoft.Windows/WindowsPowerShell` adapter. It doesn't affect +the `Microsoft.DSC/PowerShell` adapter, which doesn't rely on PSDSC 1.1. + +### Troubleshooting steps + +- Ensure all PSDSC modules required by your configuration are installed in the **AllUsers** scope. +- Reinstall the PowerShell module for any missing PSDSC resources using an elevated prompt to + guarantee system-wide availability. + +### Possible causes + +- A PSDSC resource module is installed only for the current user, not for all users. + +### Recommendation + +Install all PSDSC resource modules in the **AllUsers** scope to ensure they're available for the +`Microsoft.Windows/WindowsPowerShell` adapter. + +## Validation errors when executing dsc.exe in Windows PowerShell sessions + + + +When executing `dsc.exe` commands in Windows PowerShell sessions, you may encounter +validation errors when using manually crafted JSON input or the `ConvertTo-Json` cmdlet +with the `-Compress` parameter. This issue is related to how Windows PowerShell handles +string encoding and JSON formatting. + +### Prerequisites + +- Windows PowerShell session +- Direct execution of `dsc.exe` commands +- Use of JSON input with the `--input` parameter + +### Problem details + +When running `dsc.exe` commands in Windows PowerShell, validation errors may occur +when passing JSON input to resources. This typically happens when using manually +crafted JSON strings or when using PowerShell's `ConvertTo-Json` cmdlet with the `-Compress` parameter. + +Commands that work correctly: + +- `dsc resource get -r PSDesiredStateConfiguration/Service --input '{ "Name": "bits" }'` +- `dsc resource get -r PSDesiredStateConfiguration/Service --input (@{Name = 'bits'} | ConvertTo-Json)` + +Common error symptoms include: + +- JSON parsing failures when using compressed JSON output. +- Property validation errors with valid JSON input. +- Cannot validate argument on parameter ``. The argument is null + or empty, or an element of the argument collection contains a null value. + +### Resolution steps + +Recommend piping JSON over stdin with the --file - syntax: + +```powershell +@{ Name = 'bits' } | + ConvertTo-Json -Compress | + dsc resource get -r PSDesiredStateConfiguration/Service --file - +``` + +### Root causes + +- Windows PowerShell's handling of compressed JSON may introduce formatting issues. +- String encoding differences between Windows PowerShell and `dsc.exe`. +- JSON parsing inconsistencies when using the `-Compress` parameter with `ConvertTo-Json`. + +### Recommendation + +When executing `dsc.exe` commands in Windows PowerShell: + +- Recommend piping JSON over stdin with the --file - syntax. +- Use `ConvertTo-Json` without the `-Compress` parameter. +- Consider using PowerShell 7+ for improved JSON handling compatibility. + +## See also + +- [Microsoft Desired State Configuration overview][04] + + +[01]: https://github.com/PowerShell/DSC/issues +[02]: ../concepts/enhanced-authoring.md +[03]: ../reference/resources/Microsoft/Windows/WindowsPowerShell/index.md +[04]: ../overview.md +[#917]: https://github.com/PowerShell/DSC/issues/917 +[#765]: https://github.com/PowerShell/DSC/issues/765 +[#965]: https://github.com/PowerShell/DSC/issues/965 diff --git a/docs/troubleshooting/media/unable-to-parse-content.png b/docs/troubleshooting/media/unable-to-parse-content.png new file mode 100644 index 000000000..c206b64a9 Binary files /dev/null and b/docs/troubleshooting/media/unable-to-parse-content.png differ