Skip to content

Commit e91e4e5

Browse files
JillGrant615JillGrant615
authored
Merge pull request #13828 from GitHubber17/415544-g
410544 - MSBuild error article updates
2 parents 86f3227 + d5181e9 commit e91e4e5

File tree

10 files changed

+249
-104
lines changed

10 files changed

+249
-104
lines changed

‎docs/msbuild/errors/msb4096.md

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "MSB4096: The item 'item' in item list 'item-list' does not define a value for metadata 'name'"
3-
description: "This error occurs when your MSBuild script uses a shorthand unqualified syntax for referencing item metadata without fully qualifying it with the Item name."
4-
ms.date: "07/07/2021"
2+
title: MSB4096 diagnostic code
3+
description: Learn about the possible causes of the MSB4096 build error and get troubleshooting tips.
4+
ms.date: 04/16/2025
55
ms.topic: "error-reference"
66
f1_keywords:
77
- MSB4096
@@ -16,16 +16,22 @@ ms.author: ghogen
1616
manager: mijacobs
1717
ms.subservice: msbuild
1818
---
19-
# MSB4096: The item 'item' in item list 'item-list' does not define a value for metadata 'name'
19+
# MSB4096
2020

21-
The full error message resembles the following example:
21+
This article describes the MSB4096 error code.
2222

23-
```output
24-
MSB4096: The item 'item' in item list 'item-list' does not define a value for metadata 'name'.  In order to use this metadata, either qualify it by specifying %(item-name.metadata-name), or ensure that all items in this list define a value for this metadata.
25-
```
23+
## Message text
2624

27-
This error occurs when your MSBuild script uses a shorthand unqualified syntax for referencing item metadata `%(MetadataName)`, without fully qualifying it with the Item name, as in `%(ItemName.MetadataName)`. The error text suggests qualifying the metadata by prefixing the metadata name with the Item name. For example, `%(File.Extension)` rather than just `%(Extension)`.
25+
`MSB4096: The item 'item' in item list 'item-list' does not define a value for metadata 'name'.  In order to use this metadata, either qualify it by specifying %(item-name.metadata-name), or ensure that all items in this list define a value for this metadata.`
2826

29-
You can also avoid this error by ensuring that all items of the given type define a value for the metadata.
27+
## Description
3028

31-
See [Item metadata](../msbuild-items.md#item-metadata).
29+
This error occurs when your MSBuild script uses a shorthand unqualified syntax to reference item metadata `%(MetadataName)` without fully qualifying it with the `Item` name, as in `%(ItemName.MetadataName)`. The error text suggests qualifying the metadata by prefixing the metadata name with the `Item` name. For example, use the syntax `%(File.Extension)` rather than `%(Extension)`.
30+
31+
## Resolution
32+
33+
Ensure all items of the given type define a value for the metadata. For more information, see [Item metadata](../msbuild-items.md#item-metadata).
34+
35+
## Applies to
36+
37+
All versions of MSBuild

‎docs/msbuild/errors/msb4166.md

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "MSB4166"
3-
description: "MSBuild can use multiple processes and there's a scheduler process that distributes work to the various processor nodes. If the worker process crashes, then the scheduler emits this error."
4-
ms.date: "07/07/2021"
2+
title: MSB4166 diagnostic code
3+
description: Learn about the possible causes of the MSB4166 build error and get troubleshooting tips.
4+
ms.date: 04/16/2025
55
ms.topic: "error-reference"
66
f1_keywords:
77
- MSB4166
@@ -18,12 +18,26 @@ ms.subservice: msbuild
1818
---
1919
# MSB4166
2020

21-
```output
22-
MSB4166: Child node 'node' exited prematurely. Shutting down. Diagnostic information may be found in files in 'path' and will be named MSBuild_*.failure.txt. This location can be changed by setting the MSBUILDDEBUGPATH environment variable to a different directory.
23-
```
21+
This article describes the MSB4166 error code.
2422

25-
The error text shown is followed by the exception text, if any.
23+
## Message text
2624

27-
MSBuild can use multiple processes and there's a scheduler process that distributes work to the various worker nodes. If the worker process crashes without reporting an error to the scheduler, then the scheduler emits this error. Check the error log in the temporary files folder in *MSBuild_{guid}.failure.txt*.
25+
`MSB4166: Child node 'node' exited prematurely. Shutting down. Diagnostic information may be found in files in 'path' and will be named MSBuild_*.failure.txt. This location can be changed by setting the MSBUILDDEBUGPATH environment variable to a different directory.`
2826

29-
This error usually indicates an MSBuild issue, and should be reported to Microsoft. Please report the issue in the [MSBuild GitHub repository](https://github.com/Microsoft/msbuild) or at [Developer Community](https://developercommunity.visualstudio.com/search?space=8).
27+
## Description
28+
29+
The error output text is followed by the exception text, if any.
30+
31+
MSBuild can use multiple processes and there's a scheduler process that distributes work to the various worker nodes. If the worker process crashes without reporting an error to the scheduler, then the scheduler emits this error.
32+
33+
## Resolution
34+
35+
Check the error log in the temporary files folder in *MSBuild_{guid}.failure.txt*.
36+
37+
### Report error
38+
39+
This error usually indicates an MSBuild issue, and should be reported to Microsoft. You can report the issue in the [MSBuild GitHub repository](https://github.com/Microsoft/msbuild) or at the [Developer Community](https://developercommunity.visualstudio.com/search?space=8) site.
40+
41+
## Applies to
42+
43+
All versions of MSBuild

‎docs/msbuild/errors/msb4175.md

Lines changed: 28 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "MSB4175: The task factory 'task-factory-name' could not be loaded from the assembly 'assembly-name'."
3-
description: "This error occurs when MSBuild encounters a problem during the creation of a task using a task factory."
4-
ms.date: "07/07/2021"
2+
title: MSB4175 diagnostic code
3+
description: Learn about the possible causes of the MSB4175 build error and get troubleshooting tips.
4+
ms.date: 04/16/2025
55
ms.topic: "error-reference"
66
f1_keywords:
77
- MSB4175
@@ -16,11 +16,31 @@ ms.author: ghogen
1616
manager: mijacobs
1717
ms.subservice: msbuild
1818
---
19-
# MSB4175: The task factory 'task-factory-name' could not be loaded from the assembly 'assembly-name'
19+
# MSB4175
2020

21-
This error occurs when MSBuild encounters a problem during the creation of a task using a task factory.
21+
This article describes the MSB4175 error code.
2222

23-
When MSBuild processes a UsingTask, a task factory builds an instance of a task that is then invoked. Typically, an assembly or DLL is used, but the task might also be created dynamically from code, as in the case of `CodeTaskFactory` and `RoslynTaskFactory`, or from XAML, as in the case of `XamlTaskFactory`. A second error might give more information on the cause of the failure. Common reasons for this error include:
23+
## Message text
2424

25-
- The task assembly couldn't be loaded. Check the path and permissions on the file.
26-
- There's a coding error in the code used to dynamically create the task. The compiler error will be shown in a second error.
25+
`MSB4175: The task factory 'task-factory-name' could not be loaded from the assembly 'assembly-name'.`
26+
27+
## Description
28+
29+
This error occurs when MSBuild encounters a problem during the creation of a task by using a task factory. The output message might describe a second error that can provide more information about the cause of the failure.
30+
31+
When MSBuild processes a `UsingTask` task, a task factory builds an instance of a task which is then invoked. Typically, an assembly or DLL is used. The task might also be created dynamically from code with the `CodeTaskFactory` and `RoslynTaskFactory` tasks, for example. The task might also be created from XAML, such as by using the `XamlTaskFactory` task.
32+
33+
Common causes for this error include:
34+
35+
- The task assembly can't load due to possible errors in the path or insufficient permissions on the file.
36+
- A coding error exists in the code used to dynamically create the task. The compiler error is listed as the second error.
37+
38+
## Resolution
39+
40+
Look to the extra error information provided to determine the cause of the problem. As applicable, investigate any reported compiler errors.
41+
42+
Confirm the task assembly can load. Verify the file path is accurate and the file permissions allow sufficient access.
43+
44+
## Applies to
45+
46+
All versions of MSBuild

‎docs/msbuild/errors/msb4181.md

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "MSB4181: The 'task' task returned false but did not log an error"
3-
description: "This error occurs when a task returned false without logging an error. This indicates a failure from a task that did not report enough information about the problem."
4-
ms.date: "05/26/2021"
2+
title: MSB4181 diagnostic code
3+
description: Learn about the possible causes of the MSB4181 build error and get troubleshooting tips.
4+
ms.date: 04/16/2025
55
ms.topic: "error-reference"
66
f1_keywords:
77
- MSB4181
@@ -16,16 +16,30 @@ ms.author: ghogen
1616
manager: mijacobs
1717
ms.subservice: msbuild
1818
---
19-
# MSB4181: The 'task' task returned false but did not log an error
19+
# MSB4181
2020

21-
This error occurs when a task returned `false` to signal that it didn't complete successfully, but didn't log an error. If you see this error, it means task failed, but it didn't report a specific error with more information.
21+
This article describes the MSB4181 error code.
2222

23-
To diagnose the problem, first enable a diagnostic log (use the `-verbosity:diag` command-line switch), and check the MSBuild log file with the full diagnostics output. For bigger output logs on large projects, consider using the binary log (`-bl` command-line switch) and the [MSBuild Structured Log Viewer](https://msbuildlog.com/) to view the output more easily.
23+
## Message text
2424

25-
You can also set the `MSBuildDebugEngine` environment variable to 1 to get all possible logs. See [Building MSBuild for the .NET Framework - Logs](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Building-Testing-and-Debugging-on-Full-Framework-MSBuild.md#logs).
25+
`MSB4181: The 'task' task returned false but did not log an error.`
26+
27+
## Description
28+
29+
This error occurs when a task returns `false` to signal that it didn't complete successfully and also didn't log an error. If you see this error, it means the task failed, but there's no report with specific error information available.
30+
31+
## Resolution
32+
33+
First, enable a diagnostic log by using the `-verbosity:diag` command-line switch, and then check the MSBuild log file with the full diagnostics output. For longer output logs on large projects, consider using the binary log `-bl` command-line switch with the [MSBuild Structured Log Viewer](https://msbuildlog.com/) to view the output more easily.
34+
35+
You can also set the `MSBuildDebugEngine` environment variable to 1 to get all possible logs. For more information, see [Building MSBuild for the .NET Framework - Logs](https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Building-Testing-and-Debugging-on-Full-Framework-MSBuild.md#logs).
2636

2737
If the task ran an executable, try running the executable separately with the same inputs and command line.
2838

2939
If you know the owner of the task, consider reporting this issue to the task owner and recommending that they modify the task to log more information.
3040

31-
If it's a custom task and you are the task owner, consider improving the error logging. For example, if an API you're calling could throw an exception, add an exception handler that logs the exception message.
41+
If it's a custom task and you're the task owner, consider improving the error logging. For example, if an API you're calling might throw an exception, add an exception handler to log the exception message.
42+
43+
## Applies to
44+
45+
All versions of MSBuild

‎docs/msbuild/errors/msb4184.md

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "MSB4184: The expression 'expression' cannot be evaluated."
3-
description: "This error occurs if MSBuild can't interpret an expression found in a project file."
4-
ms.date: "08/15/2022"
2+
title: MSB4184 diagnostic code
3+
description: Learn about the possible causes of the MSB4184 build error and get troubleshooting tips.
4+
ms.date: 04/16/2025
55
ms.topic: "error-reference"
66
f1_keywords:
77
- MSB4184
@@ -18,16 +18,24 @@ ms.subservice: msbuild
1818
---
1919
# MSB4184
2020

21-
This error occurs if MSBuild can't interpret an expression found in a project file or an imported file.
21+
This article describes the MSB4184 error code.
2222

23-
The message resembles the following, but this text is followed by the exception text from the underlying code:
23+
## Message text
2424

25-
```output
26-
The expression 'expression' cannot be evaluated.
27-
```
25+
`MSB4184: The expression 'expression' cannot be evaluated.`
2826

29-
For example, if the project file contains invalid elements or value, you might get this error.
27+
## Description
28+
29+
The standard output message text is followed by the exception text from the underlying code, if any.
30+
31+
This error occurs if MSBuild can't interpret an expression found in a project file or an imported file. For example, if the project file contains invalid elements or values, you might get this error.
32+
33+
## Resolution
3034

3135
Look to the exception message provided by the underlying code to determine the cause of the problem.
3236

3337
Check the syntax of the code that resulted in the error.
38+
39+
## Applies to
40+
41+
All versions of MSBuild

‎docs/msbuild/errors/msb4236.md

Lines changed: 23 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "MSB4236: The SDK 'name' specified could not be found."
3-
description: "This error occurs when an MSBuild SDK couldn't be loaded."
4-
ms.date: "06/18/2021"
2+
title: MSB4236 diagnostic code
3+
description: Learn about the possible causes of the MSB4236 build error and get troubleshooting tips.
4+
ms.date: 04/16/2025
55
ms.topic: "error-reference"
66
f1_keywords:
77
- MSB4236
@@ -16,17 +16,27 @@ ms.author: ghogen
1616
manager: mijacobs
1717
ms.subservice: msbuild
1818
---
19-
# MSB4236: The SDK 'name' specified could not be found
19+
# MSB4236
2020

21-
This error occurs when an MSBuild project SDK couldn't be loaded. An MSBuild project SDK is a packaged set of imported files that sets up common build configuration for a build of a certain kind. For example, for .NET builds, the .NET SDK is used. See [How to use MSBuild project SDKs](../how-to-use-project-sdk.md).
21+
This article describes the MSB4236 error code.
2222

23-
To diagnose the error, first look in the project file's top-level [Project element (MSBuild)](../project-element-msbuild.md) to see what SDK is being used. Examples include the .NET SDK (Microsoft.NET.Sdk) and the ASP.NET SDK (Microsoft.NET.Sdk.Web). MSBuild project SDKs can be delivered NuGet packages.
23+
## Message text
24+
25+
`MSB4236: The SDK 'name' specified could not be found.`
26+
27+
## Description
28+
29+
This error occurs when an MSBuild project SDK can't load. An MSBuild project SDK is a packaged set of imported files that sets up common build configuration for a build of a certain kind. For example, for .NET builds, the .NET SDK is used. For more information, see [How to use MSBuild project SDKs](../how-to-use-project-sdk.md).
30+
31+
## Resolution
32+
33+
Look in the project file's top-level [Project element (MSBuild)](../project-element-msbuild.md) and identify the SDK in use. Examples include the .NET SDK (Microsoft.NET.Sdk) and the ASP.NET SDK (Microsoft.NET.Sdk.Web). MSBuild project SDKs can be delivered NuGet packages.
2434

2535
```xml
2636
<Project Sdk="Microsoft.NET.Sdk.Web">
2737
```
2838

29-
The .NET SDK shouldn't fail to load, unless [global.json](/dotnet/core/tools/global-json) points to an SDK that isn't installed. Look for the version specified in the `version` property of the `sdk` object in *global.json*:
39+
The .NET SDK usually loads, unless the [global.json](/dotnet/core/tools/global-json) file points to an SDK that isn't installed. Check for the version specified in the `version` property of the `sdk` object in the *global.json* file:
3040

3141
```json
3242
{
@@ -36,12 +46,14 @@ The .NET SDK shouldn't fail to load, unless [global.json](/dotnet/core/tools/glo
3646
}
3747
```
3848

39-
The NuGet SDK resolver can fail in the case of a network error or incorrect NuGet feed.
40-
41-
Check the top-level element in the project file to see whether an SDK version was specified, and make sure that version is installed. You can specify the version in the project file by using the following syntax:
49+
The NuGet SDK resolver can fail due to a network error or incorrect NuGet feed. Check the top-level element in the project file to see if an SDK version is specified, and make sure that specific version is installed. You can specify the version in the project file by using the following syntax:
4250

4351
```xml
4452
<Project Sdk="My.Custom.Sdk/1.0.0" />
4553
```
4654

47-
MSBuild project SDK versions can also be specified in [global.json](/dotnet/core/tools/global-json#msbuild-sdks).
55+
MSBuild project SDK versions can also be specified in the [global.json](/dotnet/core/tools/global-json#msbuild-sdks) file.
56+
57+
## Applies to
58+
59+
All versions of MSBuild

‎docs/msbuild/errors/msb6001.md

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "MSB6001: Invalid command line switch for 'tool'."
3-
description: "This error occurs when an MSBuild task was given a command-line option that was not valid."
4-
ms.date: "07/07/2021"
2+
title: MSB6001 diagnostic code
3+
description: Learn about the possible causes of the MSB6001 build error and get troubleshooting tips.
4+
ms.date: 04/16/2025
55
ms.topic: "error-reference"
66
f1_keywords:
77
- MSB6001
@@ -16,12 +16,30 @@ ms.author: ghogen
1616
manager: mijacobs
1717
ms.subservice: msbuild
1818
---
19-
# MSB6001: Invalid command line switch for 'tool'
19+
# MSB6001
2020

21-
This error occurs when an MSBuild task was given a command-line option that was not valid. Look to the second error for more details on the problem.
21+
This article describes the MSB6001 error code.
2222

23-
Common causes are:
23+
## Message text
2424

25-
- Illegal characters in a path. Check the placement of quotes to ensure they're not used inappropriately.
26-
- A spelling error in the syntax of the switch
27-
- The version of the tool you're using doesn't support that switch
25+
`MSB6001: Invalid command line switch for 'tool'.`
26+
27+
## Description
28+
29+
This error occurs when an MSBuild task is supplied an invalid command-line option. The output message contains a second error with more details about the problem.
30+
31+
Common causes of this error include:
32+
33+
- Illegal characters in a path, or incorrect placement of quotes.
34+
- A spelling error in the syntax of the switch.
35+
- The version of the tool in use doesn't support the specified switch.
36+
37+
## Resolution
38+
39+
Look to the extra error information provided to determine the cause of the problem.
40+
41+
Check for illegal characters in the path. Confirm the placement of quotes to ensure they're used appropriately.
42+
43+
## Applies to
44+
45+
All versions of MSBuild

0 commit comments

Comments
 (0)