Add details for MSBuild error messages (2 of 3) (#13915)

ghogen · web-flow · commit 75c5cffc659d · 2025-06-05T13:46:45.000-07:00
* More MSBuild error messages

* Fix errors

* Add MSB4260

* Fix various issues

* add info about long paths

* edit resolution section
diff --git a/docs/msbuild/errors/msb1022.md b/docs/msbuild/errors/msb1022.md
@@ -37,6 +37,18 @@ This article describes the MSB1022 error code.
     message does not need in-line parameters because the exception takes care of displaying the invalid arg.
     LOCALIZATION: The prefix "MSBUILD : error MSBxxxx:" should not be localized.
 -->
+## Description
+
+This error occurs if MSBuild was provided a response file at the MSBuild command line, but the file was not found. Response files typically have the extension `.rsp`. See [MSBuild response files](../msbuild-response-files.md).
+
+## Resolution
+
+Check that the response file specified in the MSBuild command line exists in the expected directory, and that the path, syntax, and spelling are correct. For paths with spaces, ensure that quotes are used to prevent the command from being misinterpreted.
+
+If the first response file contains references to other response files, be sure to check each nested response file. Check the default response files (*MSBuild.rsp* or *Directory.Build.rsp*) that are included automatically as well, if they exist and reference other response files.
+
+Be aware that some third-party tools invoke MSBuild using a generated response file in a temporary folder, based on the path specified in the TMP or TEMP environment variable. Refer to the documentation of the third-party tools to troubleshoot the problem.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3022.md b/docs/msbuild/errors/msb3022.md
@@ -35,6 +35,16 @@ This article describes the MSB3022 error code.
 <!--
 {StrBegin="MSB3022: "}
 -->
+## Description
+
+The `Copy` task can be used in one of two ways. You can specify a list that contains the destination path for each file in the source list, or you can specify a destination directory. This error occurs if you specify both a list of files and a directory.
+
+## Resolution
+
+If you control the invocation of the `Copy` task, choose the most appropriate method of specifying the destination files, and remove the other parameter.
+
+See [Copy task](../copy-task.md).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3028.md b/docs/msbuild/errors/msb3028.md
@@ -40,6 +40,14 @@ MSB3028: {0} is an invalid retry count. Value must not be negative. -->
 
 {StrBegin="MSB3028: "} LOCALIZATION: {0} is a number.
 -->
+## Description
+
+The retry count parameter of a Copy or Delete task determine how many attempts are made to perform the operation before returning an error. This must be a positive number.
+
+## Resolution
+
+Check the values provided for the parameters of the task, and if any properties are referenced, ensure the properties are defined, and the values are correct.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3094.md b/docs/msbuild/errors/msb3094.md
@@ -37,6 +37,14 @@ This article describes the MSB3094 error code.
 
 {StrBegin="MSB3094: "}
 -->
+## Description
+
+In certain operations, MSBuild tasks accept two input parameters that represent lists of items, such as sets of source and destination files for the Copy task. The logic of the task requires that the lists have the same number of items. If there's a mismatch in the number of items when they should be the same, you get this error.
+
+## Resolution
+
+The error message points to the items and the counts of each item. Check the items and how they're created for logic or syntax errors.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3171.md b/docs/msbuild/errors/msb3171.md
@@ -35,6 +35,16 @@ This article describes the MSB3171 error code.
 <!--
 {StrBegin="MSB3171: "}
 -->
+## Description
+
+This error is a generic error that you get when MSBuild is unable to provide a more specific error about the exact problem that occurred when trying to generate a manifest.
+
+## Resolution
+
+Try running with verbose diagnostics (`-v:diag` on the MSBuild command line), and check everything related to signing the assembly, and the ClickOnce manifest generation. In Visual Studio, go to Project Properties (press **Alt**+**Enter**), and check the **Strong naming** settings under the **Build** section. Verify the correctness of any information provided, such as the key file. On Windows, type **certmgr.msc** in the search section of the taskbar to open the certificate management console. Check any relevant certificates in the certificate store on the machine.
+
+You can also generate a binary log using the `-bl` option, and use the [MSBuild Structured Log Viewer](https://msbuildlog.com) to get more details about what was happening in the build process before the error occurred.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb3248.md b/docs/msbuild/errors/msb3248.md
@@ -32,12 +32,10 @@ This article describes the MSB3248 error code.
 <!-- MSB3248: Parameter "{0}" has invalid value "{1}". {2} -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
-## Remarks
+## Description
 
 The error code MSB3248 occurs in the `ResolveAssemblyReference` task in MSBuild when there's an issue with the parameters specified for resolving assembly references. The `ResolveAssemblyReference` task is responsible for resolving assembly references in a project. You don't normally invoke this task directly; it's called during the .NET build process.
 
-### Common causes
-
 The most likely cause is an MSBuild property setting that creates an issue with the assembly resolution process. See [Common MSBuild properties](../common-msbuild-project-properties.md).
 
 ## Resolution
diff --git a/docs/msbuild/errors/msb4020.md b/docs/msbuild/errors/msb4020.md
@@ -36,6 +36,18 @@ This article describes the MSB4020 error code.
 {StrBegin="MSB4020: "}UE: This is a generic message that is displayed when we find a project element with an incorrect value for one of its
     attributes e.g. <Import Project=""> -- the value of Project should not be an empty string.
 -->
+## Description
+
+This error occurs when a project element has an incorrect value for one of its attributes. For example, an `Import` element with an empty string for the Project.
+
+```xml
+<Import Project="">
+```
+
+## Resolution
+
+Check the attribute and value referenced in the text of the error message. If the values provided are determined by properties, ensure that the properties are defined and have the correct values.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4061.md b/docs/msbuild/errors/msb4061.md
@@ -35,6 +35,15 @@ This article describes the MSB4061 error code.
 <!--
 {StrBegin="MSB4061: "}LOCALIZATION: "{2}" is a localized message from a CLR/FX exception.
 -->
+## Description
+
+This error occurs when MSBuild tries to create a task, but the task creation fails. If this occurs with a build system task, it's usually due to an installation issue. If this occurs with your own custom task, it means that something failed, perhaps in the task constructor.
+
+## Resolution
+
+Reinstall MSBuild or the .NET SDK, or repair your installation of Visual Studio. See [Repair Visual Studio](../../install/repair-visual-studio.md).
+
+For your own custom tasks, you have to debug the issue. Set breakpoint in the task constructor to see if the constructor gets called, and executes successfully. Consider adding error checks or logging information in the constructor code. For more information about debugging and testing a custom task, see [Create a custom task for code generation - Generate a console app and use the custom task](../tutorial-custom-task-code-generation.md#generate-a-console-app-and-use-the-custom-task).
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4068.md b/docs/msbuild/errors/msb4068.md
@@ -35,6 +35,18 @@ This article describes the MSB4068 error code.
 <!--
 {StrBegin="MSB4068: "}
 -->
+## Description
+
+This error occurs when MSBuild is given an XML file to build, but the file isn't a project file. Specifically, MSBuild looks for the top-level `Project` XML element to see if it can process the input file as a valid project file, and if it doesn't find it, you get this error. The error text gives the name of whatever top-level element that was found.
+
+## Resolution
+
+Check the file that was provided. Note that the file MSBuild tries to build might be found automatically. For example, if you invoke MSBuild in a project folder, it tries to find the project file or a solution file in that folder. 
+
+If you were using a tool that runs MSBuild, such as `dotnet pack`, check its documentation to ensure it is being invoked correctly. For example, if you invoke `dotnet pack` with a `.nuspec` file, which uses a different XML schema, the error references the `package` element found in those files.
+
+If the provided file is a project file, check for any spelling or syntax errors in or near the top-level `Project` element.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4078.md b/docs/msbuild/errors/msb4078.md
@@ -35,6 +35,16 @@ This article describes the MSB4078 error code.
 <!--
 {StrBegin="MSB4078: "}
 -->
+## Description
+
+This error occurs when a project file contains a project of a type that can't be built by MSBuild. Most modern project types support MSBuild, but some older project types in Visual Studio, and project types supported in Visual Studio extensions, do not.
+
+This issue only occurs when you build from the MSBuild or `dotnet` command line; the solution should still build in Visual Studio, if the required workloads, components, and extensions are installed.
+
+## Resolution
+
+If your solution contains project types that don't support MSBuild, use `devenv /build` to build the solution on the command line. See [/Build (devenv.exe)](../../ide/reference/build-devenv-exe.md).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4185.md b/docs/msbuild/errors/msb4185.md
@@ -37,6 +37,16 @@ This article describes the MSB4185 error code.
       UE: This message is shown when the user attempts to provide an expression like "$([System.DateTime]::Now)", but the expression has not been enabled
       LOCALIZATION: "{0}" is the static function name, "{1}" is the .NET Framework type name
 -->
+## Description
+
+This error occurs when a [property function](../property-functions.md) is used that is not supported by MSBuild.
+
+## Resolution
+
+First, check for typos or misspellings in the property function mentioned in the error message.
+
+The problem could occur if the project is using functionality that was added in a newer version of MSBuild, but you're building with an older version. Install the latest version of Visual Studio or MSBuild and try building again. See [Install Visual Studio](../../install/install-visual-studio.md) and [MSBuild - Install MSBuild](../msbuild.md#install-msbuild).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4186.md b/docs/msbuild/errors/msb4186.md
@@ -38,7 +38,7 @@ This article describes the MSB4186 error code.
       LOCALIZATION: "{0}" is the function expression which is in error. "{1}" is a message from an FX exception that describes why the expression is bad.
 -->
 
-## Remarks
+## Description
 
 This error occurs when MSBuild encounters a function invocation that uses an invalid syntax for calling a static method. In MSBuild, static methods must be invoked using the correct syntax: `$([FullTypeName]::Method(Parameters))`.
 
@@ -51,6 +51,9 @@ To resolve this error, ensure that the static method is invoked using the proper
     <MyProperty>$([ClassName]::MethodName('a', 'b'))</MyProperty>
 </PropertyGroup>
 ```
+
+Check the parameters and ensure that the parameters are correct for the method, and if any properties are referenced in the expression, that the properties are defined, and have the correct values, and that the values provided for method parameters are valid inputs that match the type of each parameter.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4246.md b/docs/msbuild/errors/msb4246.md
@@ -35,6 +35,14 @@ This article describes the MSB4246 error code.
 <!--
 {StrBegin="MSB4246: "}
 -->
+## Description
+
+Modern MSBuild project files reference a project SDK by using the `Sdk` attribute. See [Project SDKs](../how-to-use-project-sdk.md) To resolve the attribute value, MSBuild uses the SDK Resolver. If the resolver assemblies are not found in the expected installation folders, you get this error.
+
+## Resolution
+
+Reinstall MSBuild or the .NET SDK, or repair your installation of Visual Studio. See [Repair Visual Studio](../../install/repair-visual-studio.md).
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4248.md b/docs/msbuild/errors/msb4248.md
@@ -39,17 +39,9 @@ This article describes the MSB4248 error code.
 -->
 ## Remarks
 
-The MSB4248 error occurs when MSBuild is unable to expand item metadata in a build operation. This situation typically happens when metadata references are used in an invalid context or when the metadata being referenced doesn't exist for the item.
+The MSB4248 error occurs when MSBuild is unable to expand item metadata in a build operation. This situation typically happens when metadata references are used in an invalid context or when the metadata being referenced doesn't exist for the item. For example, the built-in metadata for `SomeItem->%(Extension)` was used, but the item isn't a file.
 
-## Possible causes
-
-This error can be raised for the following reasons:
-
-1. **Metadata not supported for the item**
-   For example, referencing %(RootDir) on an item that isn't a path.
-
-1. **Dynamic item metadata in complex builds**
-   - Dynamically generated item metadata may not always be available, depending on the build configuration.
+This error can also occur when file paths exceed the maximum path length. If you use long paths, check the Windows operating system `LongPathsEnabled` setting. For more information, see [Maximum file path limitation](/windows/win32/fileio/maximum-file-path-limitation?tabs=cmd).
 
 ## Resolution
 
@@ -61,6 +53,9 @@ This error can be raised for the following reasons:
      ```xml
      <Message Text="Target Framework: %(Metadataname)" Condition="'%(Metadataname)' != ''" />
      ```
+
+1. **Enable long paths on the Windows operating system**.
+
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
diff --git a/docs/msbuild/errors/msb4260.md b/docs/msbuild/errors/msb4260.md
@@ -27,14 +27,21 @@ This article describes the MSB4260 error code.
 ## Message text
 
 <!-- :::editable-content name="messageText"::: -->
-`MSB4260: Project 'value' skipped graph isolation constraints on referenced project 'value'`
+`MSB4260: Project 'project1' skipped graph isolation constraints on referenced project 'project2'`
 <!-- :::editable-content-end::: -->
 <!-- MSB4260: Project "{0}" skipped graph isolation constraints on referenced project "{1}" -->
 
 <!-- :::editable-content name="postOutputDescription"::: -->
 <!--
 LOCALIZATION: {0} and {1} are file paths
 -->
+## Description
+
+This error occurs when you're using graph mode (`-graph` or `-graphBuild` command-line option) with the isolation option (`-isolate` or `-isolateProject` command-line option) set to `MessageUponIsolationViolation`, and, as described in the [MSBuild command-line reference](../msbuild-command-line-reference.md), there's a project that violates the isolation constraints. A project that isolates the violation constraints can still be built, but it can only be built in real time, not ahead of time and cached. Therefore the cached, serialized output of the project isn't usable. This message is not an error, but it points to an incompatibility between the specified project and the optimum function of the project isolation build mode.
+
+## Resolution
+
+If you can find a way to avoid the isolation constraint, perhaps by removing any build side-effects or avoiding project types that inherently violate the isolation constraints (such as XAML projects), you can avoid the situation that leads to this message.
 <!-- :::editable-content-end::: -->
 <!-- :::ErrorDefinitionDescription-end::: -->
 
