Merge pull request #13939 from ghogen/msbuild-errors-june-2025

v-regandowner · web-flow · commit a7566dcc857e · 2025-06-02T16:57:48.000-04:00
Add details for MSBuild error messages (3 of 3)
diff --git a/docs/msbuild/errors/msb1025.md b/docs/msbuild/errors/msb1025.md
@@ -37,6 +37,16 @@ This article describes the MSB1025 error code.
       FX/CLR method threw an unexpected exception.
       LOCALIZATION: The prefix "MSBUILD : error MSBxxxx:" and "MSBuild" should not be localized.
 -->
+## Description
+
+This error occurs when MSBuild itself generates a fatal error while building your project. This situation could occur if MSBuild encounters an error that it wasn't expecting, such as when your system is out of memory, or it could indicate an engineering defect in MSBuild. The exception is reported after the MSBuild message text.
+
+## Resolution
+
+If the exception text indicates a system issue, such as an out-of-memory error, address that if you can, and then try rerunning MSBuild. For an out-of-memory issue, close open applications. On Windows, use the Task Manager to identify processes that are using up memory, and shut them down. Check for any bad processes that might be using up memory erroneously.
+
+If the exception text isn't obviously a system issue, you can report the issue either as a Visual Studio bug, or as a MSBuild issue. See [Report a problem](../../ide/how-to-report-a-problem-with-visual-studio.md) or the [MSBuild GitHub repository](https://github.com/dotnet/msbuild).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3096.md b/docs/msbuild/errors/msb3096.md
@@ -27,14 +27,37 @@ This article describes the MSB3096 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3096: Task 'value' is only supported when building on Windows.`
+`MSB3096: Task 'task-name' is only supported when building on Windows.`
 <!-- :::editable-content-end::: -->
 <!-- MSB3096: Task "{0}" is only supported when building on Windows. -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3096: "}
 -->
+## Description
+
+Certain tasks are only supported on Windows, because they use resources or tools that are only available on the Windows operating system. If you're building a project that depends on these tasks on another operating system, such as Linux or macOS, then you get this error. The tasks that produce this error are only relevant on Windows, because they relate to Windows-specific features such as application manifests.
+
+The following tasks are only supported on Windows:
+
+- [GenerateApplicationManifest](../generateapplicationmanifest-task.md)
+- [GenerateDeploymentManifest](../generatedeploymentmanifest-task.md)
+- GenerateLauncher
+- GenerateManifestBase
+- GetInstalledSDKLocations
+- GetSDKReferenceFiles
+- ResolveSDKReference
+- [SignFile](../signfile-task.md)
+
+## Resolution
+
+Build the project on Windows, if that is appropriate in your situation. In CI/CD environments, check pipeline configurations and be sure the pipeline is requesting a Windows build agent for the project.
+
+For projects that are intended to build on Linux or macOS, you need to find out where in your build logic the request to the task mentioned in the error message is coming from. Turn on verbose diagnostics (use the `-v:diag` command-line switch), or generate a binary log (`-bl` command-line switch) and use the [MSBuild Structured Log Viewer](https://msbuildlog.com) to debug the build logic.
+
+Check the documentation for the task in the [MSBuild task reference](../msbuild-task-reference.md) to see what its requirements are, and if any equivalent exists that supports your operating system.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3097.md b/docs/msbuild/errors/msb3097.md
@@ -27,14 +27,22 @@ This article describes the MSB3097 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3097: File 'value' is not a valid assembly.`
+`MSB3097: File 'filename' is not a valid assembly.`
 <!-- :::editable-content-end::: -->
 <!-- MSB3097: File "{0}" is not a valid assembly. -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3097: "}
 -->
+## Description
+
+This error occurs when MSBuild tries to register an assembly for COM, but it failed.
+
+## Resolution
+
+Check the assembly mentioned in the error text to see if it built correctly and it's registerable for COM. Try registering it from the command-line using the command-line tools, [regasm.exe](/dotnet/framework/tools/regasm-exe-assembly-registration-tool) to see if it gives an error message that gives information about the problem.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3172.md b/docs/msbuild/errors/msb3172.md
@@ -35,6 +35,14 @@ This article describes the MSB3172 error code.
 <!--
 {StrBegin="MSB3172: "}
 -->
+## Description
+
+This error occurs when MSBuild tries to read a manifest file, but some error occurs. The text from MSBuild is followed by a more detailed error message from the operating system.
+
+## Resolution
+
+Look to the detailed message for more information about the problem. Open the manifest file in an XML editor and check for any invalid syntax, or other unexpected or incorrect changes to the file.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3232.md b/docs/msbuild/errors/msb3232.md
@@ -35,6 +35,16 @@ This article describes the MSB3232 error code.
 <!--
 {StrBegin="MSB3232: "}
 -->
+## Description
+
+This warning occurs when MSBuild tries to remove a directory, but the directory provided to the `RemoveDir` task was an empty string. See [RemoveDir task](../removedir-task.md).
+
+## Resolution
+
+If you're using `RemoveDir` in your project code or your own imported MSBuild files, review the parameters for the `RemoveDir` task, and make sure they're correct. Check that any property values provided have been defined at the point of the call, and have the correct value.
+
+To find the `RemoveDir` code that produces the error and debug its parameters, enable diagnostic logging (use the `-v:diag` command-line switch for MSBuild), or generate a binary log (use the `-bl` switch) and use the [MSBuild structured log viewer](https://msbuildlog.com).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3268.md b/docs/msbuild/errors/msb3268.md
@@ -27,14 +27,28 @@ This article describes the MSB3268 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB3268: The primary reference 'value' could not be resolved because it has an indirect dependency on the framework assembly 'value' which could not be resolved in the currently targeted framework. 'value'. To resolve this problem, either remove the reference 'value' or retarget your application to a framework version which contains 'value'.`
+`MSB3268: The primary reference 'assembly' could not be resolved because it has an indirect dependency on the framework assembly 'framework-assembly' which could not be resolved in the currently targeted framework. 'framework'. To resolve this problem, either remove the reference 'assembly' or retarget your application to a framework version which contains 'framework'.`
 <!-- :::editable-content-end::: -->
 <!-- MSB3268: The primary reference "{0}" could not be resolved because it has an indirect dependency on the framework assembly "{1}" which could not be resolved in the currently targeted framework. "{2}". To resolve this problem, either remove the reference "{0}" or retarget your application to a framework version which contains "{1}". -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB3268: "}
 -->
+## Description
+
+This warning occurs when your project references an assembly that itself has a dependency on a framework assembly that requires a different version of the framework. This is a warning because there's a risk to using the assembly in that case due to the version incompatibility.
+
+## Resolution
+
+As the error text indicates, there are multiple ways to resolve the issue. Which solution is appropriate in your situation depends on the project requirements and on how your project's code depends on the assembly that triggered the error.
+
+- If you can target the application to the version of the framework mentioned in the error message text, then that would solve the issue. You might need to update your code if there are any compatibility issues with the updated framework version.
+- If you have a project requirement to target a particular framework version, then you can't use the version of the assembly you tried to reference. Try to find an earlier version of that assembly that that works with the framework you're targeting.
+- If there is no version of the assembly that's compatible with the framework version you're targeting, and you can't change the targeted framework version, then your only option is to not use that assembly. You then need to find a way to rewrite your code to avoid the dependency on that assembly.
+
+For more information, see [Troubleshoot assembly references](../troubleshoot-assembly-references.md).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3374.md b/docs/msbuild/errors/msb3374.md
@@ -35,6 +35,19 @@ This article describes the MSB3374 error code.
 <!--
 {StrBegin="MSB3374: "}
 -->
+## Description
+
+The error occurs when MSBuild tries to update the timestamp on a file, but it couldn't be updated. This could occur when the file exists, but its permissions are set to not allow write access, or it could occur when some other program, such as Antivirus software, has a lock on the file. The error from the operating system is shown after the MSBuild message text. In the case of a file lock, the message might contain the process or application that has the lock.
+
+## Resolution
+
+If the error indicates a permissions issue, update the file permissions to allow write access to the account that runs MSBuild.
+
+If the error indicates a file was locked, if the message indicates the service, process or application that has the lock, try to disable the service, kill the process, or shut down the application. You can also try building again or building again after a system reboot.
+
+If the file is generated by the build, review the part of the build process that generates that file and see if its permissions are being set incorrectly.
+
+To help debug the issue use the diagnostic logs (`-v:diag` command-line option) or generate a binary log (`-bl` command-line option) and view it in the [MSBuild structured log viewer](https://msbuildlog.com).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3568.md b/docs/msbuild/errors/msb3568.md
@@ -35,6 +35,18 @@ This article describes the MSB3568 error code.
 <!--
 {StrBegin="MSB3568: "}
 -->
+## Description
+
+This error occurs when a resource file has more than one resource with the same name.
+
+## Resolution
+
+The resource name that has more than one occurrence is listed in the error message. If this is a manually maintained text resource file (`.resx` file) or binary resource file (`.resources` file), open the file in a resource editing tool such as Visual Studio, and manually remove the duplicate resources.
+
+If the duplicate resource is from an automatically generated resource file, check the inputs to the script or tool that that modifies or generates the resource file.
+
+For more information, see [Create resource files for .NET apps](/dotnet/core/extensions/create-resource-files).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4017.md b/docs/msbuild/errors/msb4017.md
@@ -28,8 +28,7 @@ This article describes the MSB4017 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB4017: The build stopped unexpectedly because of an unexpected logger failure.
-MSB4017: The build stopped unexpectedly because of an unexpected logger failure.`
+`MSB4017: The build stopped unexpectedly because of an unexpected logger failure.`
 <!-- :::editable-content-end::: -->
 <!-- MSB4017: The build stopped unexpectedly because of an unexpected logger failure.
 MSB4017: The build stopped unexpectedly because of an unexpected logger failure.
@@ -47,6 +46,15 @@ MSB4017: The build stopped unexpectedly because of an unexpected logger failure.
 -->
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
+## Description
+
+This error occurs when a logger fails while logging an event, most likely because of a programming error in the logger. When a logger encounters a fatal error, MSBuild can't continue with the build, and you get this error. The message text from MSBuild is followed by the exception or error from the logger.
+
+## Resolution
+
+If this is occurring when using your own custom logger, you have to debug the logger itself to diagnose and fix the error, and then rebuild the logger and try building again.
+
+If this occurs with a built-in logger, then it's either an engineering defect in MSBuild, or a system issue such as an out-of-memory error. If you suspect a MSBuild bug, see [Report a problem](../../ide/how-to-report-a-problem-with-visual-studio.md), or enter an issue at [https://github.com/dotnet/msbuild].
 
 ## Applies to
 
diff --git a/docs/msbuild/errors/msb4023.md b/docs/msbuild/errors/msb4023.md
@@ -37,6 +37,16 @@ This article describes the MSB4023 error code.
     %(RootDir) to an item-spec that's not a valid path, would result in this error.
     LOCALIZATION: "{1}" is a localized message explaining the problem.
 -->
+## Description
+
+This error occurs when the value of an item metadata can't be computed, usually because the item wasn't a file or path, but the metadata only applies to files or paths. For example, this error occurs if you try to invoke the `%(RootDir)` metadata, but the item is not a path.
+
+## Resolution
+
+Review the build logic in the project file or one of its imported where the error occurred. Check that the item in the expression that causes this error is valid and set correctly, or remove the use of that metadata. Refer to the documentation for the metadata at [MSBuild well-known item metadata](../msbuild-well-known-item-metadata.md).
+
+To help debug the issue, generate a diagnostic log (use the `-v:diag` MSBuild command-line option), or generate a binary log (`-bl` command-line option) and use the [MSBuild Structured Log Viewer](https://msbuildlog.com).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4027.md b/docs/msbuild/errors/msb4027.md
@@ -35,6 +35,14 @@ This article describes the MSB4027 error code.
 <!--
 {StrBegin="MSB4027: "}
 -->
+## Description
+
+This error occurs when there's a problem with the specified output item returned from a MSBuild task. MSBuild tasks may be system tasks, or custom tasks. System tasks shouldn't produce this error, but a custom task could produce this error if there's a logic problem in the task implementation, such as a type conversion that fails.
+
+## Remarks
+
+If the task given in the error message is one your own custom task, you can debug the task to see why it's returning invalid items for the specified output parameter.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4107.md b/docs/msbuild/errors/msb4107.md
@@ -35,6 +35,14 @@ This article describes the MSB4107 error code.
 <!--
 {StrBegin="MSB4107: "}
 -->
+## Description
+
+This error occurs when MSBuild tries to parse the syntax for an item list, but the syntax is incorrect. The correct syntax for an item list is `@(ItemList)`. See [MSBuild items](../msbuild-items.md).
+
+## Resolution
+
+Correct the syntax and try building again.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4801.md b/docs/msbuild/errors/msb4801.md
@@ -27,14 +27,24 @@ This article describes the MSB4801 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB4801: The task factory 'value' is not supported on the .NET Core version of MSBuild.`
+`MSB4801: The task factory 'task-factory' is not supported on the .NET Core version of MSBuild.`
 <!-- :::editable-content-end::: -->
 <!-- MSB4801: The task factory "{0}" is not supported on the .NET Core version of MSBuild. -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 {StrBegin="MSB4801: "}
 -->
+## Description
+
+This error usually occurs when you're targeting .NET Core or .NET or later, but a task was provided the `CodeTaskFactory` for the `TaskFactory` parameter in a `UsingTask` element. Every task has a task factory, which is used by MSBuild to instantiate and launch the task. For code-based tasks, .NET Framework can use the `CodeTaskFactory`, but .NET Core requires `RoslynCodeTaskFactory`.
+
+For more information, see [RoslynCodeTaskFactory](../msbuild-roslyncodetaskfactory.md).
+
+## Resolution
+
+When you're targeting .NET Core or .NET 5 and later, you must use `RoslynCodeTaskFactory` instead of `CodeTaskFactory`. Note that `RoslynCodeTaskFactory` also works for .NET Framework, so you can safely update any references to `CodeTaskFactory` to `RoslynCodeTaskFactory` regardless of target framework.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb5009.md b/docs/msbuild/errors/msb5009.md
@@ -40,6 +40,14 @@ MSB5009: Error parsing the nested project section in solution file. -->
 
 {StrBegin="MSB5009: "}UE: The solution filename is provided separately to loggers.
 -->
+## Description
+
+MSBuild generates this error when it tries to build a solution file (`.sln`) that has been corrupted and couldn't be parsed. This usually means a solution file was modified in a way that violated its expected structure and format.
+
+## Resolution
+
+If the solution file was edited, you can usually go back to an earlier revision before the change. You can also try opening the solution in Visual Studio to regenerate the solution file. Visual Studio can usually repair a corrupted solution file. In severe cases, you can try deleting the solution file and manually recreating it using Visual Studio.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
