Skip to content

Commit b64465a

Browse files
michaeltlombardimichaeltlombardi
authored
Merge pull request #926 from Gijsreyn/troubleshoot-issues
Troubleshoot issues
2 parents 09e7606 + a77a268 commit b64465a

File tree

2 files changed

+160
-0
lines changed

2 files changed

+160
-0
lines changed

‎docs/troubleshooting/known-issues.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: 'Known issues: Microsoft Desired State Configuration'
3+
description: "Troubleshooting and known issues for Microsoft Desired State Configuration (DSC)."
4+
author: michaeltlombardi
5+
ms.author: mlombardi
6+
ms.service: dsc
7+
ms.topic: troubleshooting-known-issue
8+
ms.date: 07/14/2025
9+
---
10+
11+
# Known issues: Microsoft Desired State Configuration
12+
13+
This article lists known issues and troubleshooting guidance for Microsoft Desired State Configuration (DSC).
14+
15+
The following table lists known issues with Microsoft DSC v3:
16+
17+
| Issue | Description | Status | Reported on |
18+
|:--------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------|:---------:|:------------:|
19+
| [Unable to parse content from `<manifestUrl>`](#t01) | When authoring a resource manifest in VS Code, you may encounter parsing errors. | Confirmed | [#917][#917] |
20+
| [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] |
21+
| [Validation errors when executing dsc.exe in Windows PowerShell sessions](#t03) | DSC raises input validation errors when invoked in Windows PowerShell | Confirmed | [#965][#965] |
22+
23+
For the most up-to-date information on known issues, see the [DSC GitHub repository issues][01].
24+
25+
## Unable to parse content from `<manifestUrl>`
26+
27+
<a id="t01"></a>
28+
29+
When authoring a resource manifest in Visual Studio Code (VS Code), you may encounter a parsing error:
30+
31+
> Unable to parse content from `<manifestUrl>`
32+
33+
This error occurs because canonical schema bundling isn't fully supported in VS Code. Canonical
34+
schema bundling was introduced with the 2020-12 JSON schema specification.
35+
36+
### Prerequisites
37+
38+
- Visual Studio Code
39+
- Microsoft DSC v3.0 or later
40+
41+
### Troubleshooting steps
42+
43+
To resolve this issue, use `manifest.vscode.json` in the schema URI for your resource manifest.
44+
This enables enhanced authoring support in VS Code.
45+
46+
For more information, see [Enhanced authoring][02].
47+
48+
### Possible causes
49+
50+
- The resource manifest references a schema that isn't compatible with the VS Code JSON schema parser.
51+
- VS Code doesn't currently support parsing canonically bundled schemas.
52+
53+
## Resource not found when using Windows PowerShell adapter
54+
55+
<a id="t02"></a>
56+
57+
When running DSC configurations with the `Microsoft.Windows/WindowsPowerShell` adapter, you may
58+
encounter errors indicating that a required resource cannot be found.
59+
60+
### Prerequisites
61+
62+
- Windows PowerShell DSC (PSDSC) 1.1 (included with Windows)
63+
- Using the `Microsoft.Windows/WindowsPowerShell` adapter in a configuration document or to
64+
directly invoke a resource
65+
66+
### Issue description
67+
68+
The [Microsoft.Windows/WindowsPowerShell][03] adapter relies on PSDSC 1.1, which uses the Local
69+
Configuration Manager (LCM) running as a Windows service. By design, the LCM service only accesses
70+
resources installed in the **AllUsers** scope under the Program Files directory. If a PSDSC module
71+
is installed for the current user only, the service cannot detect or use it, resulting in a
72+
"resource not found" error.
73+
74+
This limitation is specific to the `Microsoft.Windows/WindowsPowerShell` adapter. It doesn't affect
75+
the `Microsoft.DSC/PowerShell` adapter, which doesn't rely on PSDSC 1.1.
76+
77+
### Troubleshooting steps
78+
79+
- Ensure all PSDSC modules required by your configuration are installed in the **AllUsers** scope.
80+
- Reinstall the PowerShell module for any missing PSDSC resources using an elevated prompt to
81+
guarantee system-wide availability.
82+
83+
### Possible causes
84+
85+
- A PSDSC resource module is installed only for the current user, not for all users.
86+
87+
### Recommendation
88+
89+
Install all PSDSC resource modules in the **AllUsers** scope to ensure they're available for the
90+
`Microsoft.Windows/WindowsPowerShell` adapter.
91+
92+
## Validation errors when executing dsc.exe in Windows PowerShell sessions
93+
94+
<a id="t03"></a>
95+
96+
When executing `dsc.exe` commands in Windows PowerShell sessions, you may encounter
97+
validation errors when using manually crafted JSON input or the `ConvertTo-Json` cmdlet
98+
with the `-Compress` parameter. This issue is related to how Windows PowerShell handles
99+
string encoding and JSON formatting.
100+
101+
### Prerequisites
102+
103+
- Windows PowerShell session
104+
- Direct execution of `dsc.exe` commands
105+
- Use of JSON input with the `--input` parameter
106+
107+
### Problem details
108+
109+
When running `dsc.exe` commands in Windows PowerShell, validation errors may occur
110+
when passing JSON input to resources. This typically happens when using manually
111+
crafted JSON strings or when using PowerShell's `ConvertTo-Json` cmdlet with the `-Compress` parameter.
112+
113+
Commands that work correctly:
114+
115+
- `dsc resource get -r PSDesiredStateConfiguration/Service --input '{ "Name": "bits" }'`
116+
- `dsc resource get -r PSDesiredStateConfiguration/Service --input (@{Name = 'bits'} | ConvertTo-Json)`
117+
118+
Common error symptoms include:
119+
120+
- JSON parsing failures when using compressed JSON output.
121+
- Property validation errors with valid JSON input.
122+
- Cannot validate argument on parameter `<parameterName>`. The argument is null
123+
or empty, or an element of the argument collection contains a null value.
124+
125+
### Resolution steps
126+
127+
Recommend piping JSON over stdin with the --file - syntax:
128+
129+
```powershell
130+
@{ Name = 'bits' } |
131+
ConvertTo-Json -Compress |
132+
dsc resource get -r PSDesiredStateConfiguration/Service --file -
133+
```
134+
135+
### Root causes
136+
137+
- Windows PowerShell's handling of compressed JSON may introduce formatting issues.
138+
- String encoding differences between Windows PowerShell and `dsc.exe`.
139+
- JSON parsing inconsistencies when using the `-Compress` parameter with `ConvertTo-Json`.
140+
141+
### Recommendation
142+
143+
When executing `dsc.exe` commands in Windows PowerShell:
144+
145+
- Recommend piping JSON over stdin with the --file - syntax.
146+
- Use `ConvertTo-Json` without the `-Compress` parameter.
147+
- Consider using PowerShell 7+ for improved JSON handling compatibility.
148+
149+
## See also
150+
151+
- [Microsoft Desired State Configuration overview][04]
152+
153+
<!-- Link references -->
154+
[01]: https://github.com/PowerShell/DSC/issues
155+
[02]: ../concepts/enhanced-authoring.md
156+
[03]: ../reference/resources/Microsoft/Windows/WindowsPowerShell/index.md
157+
[04]: ../overview.md
158+
[#917]: https://github.com/PowerShell/DSC/issues/917
159+
[#765]: https://github.com/PowerShell/DSC/issues/765
160+
[#965]: https://github.com/PowerShell/DSC/issues/965

‎docs/troubleshooting/media/unable-to-parse-content.png

26.6 KB
Loading

0 commit comments

Comments
 (0)