排查导入和迁移错误

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

数据迁移工具在执行向 Azure DevOps Services 的迁移之前，先标记需要更正的错误。 本文介绍在准备迁移时可能收到的最常见警告和错误。 更正每个错误后，再次运行 迁移程序验证 命令以验证解决方法。

注意

建议使用 迁移指南 完成导入。 本指南根据需要链接到技术文档。

随着 Azure DevOps Server 2019 的发布，Team Foundation Server （TFS） 数据库导入服务已重新打造品牌，成为 Azure DevOps 的数据迁移工具。 数据迁移工具 TfsMigrator 已将迁移程序重命名为短。 该服务仍与以前的导入服务完全相同。 如果使用 TFS 作为品牌，则仍可以使用 迁移器 迁移到 Azure DevOps，前提是升级到某个受支持的版本， 本地版本为旧版本。 有关详细信息，请参阅 将数据从 Azure DevOps Server 迁移到 Azure DevOps Services。

消除大小警告

运行数据迁移工具后，超大型集合可能会生成以下消息之一。 如果收到上述任何警告或错误，建议尝试 减小数据库的大小。

数据库大小超过建议大小

以下警告意味着需要使用 SQL Azure VM 方法来完成导入。 数据库达到特定大小后，设置 SQL Azure VM 以完成导入到 Azure DevOps Services 的速度会更快。 若要设置 VM 并完成导入，请按照警告消息链接的说明进行操作。

The database is currently {Database Size}GBs. This is above the recommended size of {DACPAC Size Limit}GBs to use the DACPAC import method. Please see the following page to learn how to import using a SQL Azure VM: https://aka.ms/AzureDevOpsImportLargeCollection

此警告 并不意味着 集合太大，无法导入。

超出建议大小的表大小

与前面的警告类似，以下警告意味着必须使用 SQL Azure 虚拟机（VM）方法来完成导入。 按照从警告消息链接的说明设置 VM 并完成导入。

The largest table size is currently {Table size}GBs. This is above the recommended size of {Size limit}GBs to use the DACPAC import method. Please see the following page to learn how to import using a SQL Azure VM: https://aka.ms/AzureDevOpsImportLargeCollection  

此警告 并不意味着 集合太大，无法导入。

数据库元数据大小超过建议的大小

以下警告表示数据库即将达到元数据总大小限制。 元数据大小是指数据库的大小，而不包括文件、代码和其他二进制数据。 建议在 导入之前减小数据库的大小 。 减小大小可提供加快导入速度的另一个好处。

The database metadata size is currently {Metadata Size}GBs. This is above the recommended size of {Warning Size}GBs. It's recommended that you consider cleaning up older data as described in [Cleaning up old data](/azure/devops/server/upgrade/clean-up-data).

警告 并不意味着 集合太大，无法导入，而是其元数据大小大于大多数其他数据库。

数据库元数据大小超过支持的最大大小

与前面的警告不同，以下错误 将 阻止你继续迁移。

它指示集合中的元数据量太大。 若要继续导入，需要 减小 超出指示的限制的大小。

The database metadata size is currently {Metadata Size}GBs. This is above the maximum supported size of {Metadata Limit}GBs.

消除排序规则警告

排序规则警告是指集合数据库的排序规则。 排序规则控制字符串值的排序和比较方式。 未使用或SQL_Latin1_General_CP1_CI_ASLatin1_General_CI_AS接收其中一条警告消息的集合。

无本机支持

收到以下警告意味着在执行导入之前，需要考虑排序规则含义。

The collection database's collation '{collation}' is not natively supported in Azure DevOps Services. Importing your collection will result in your collation being converted to one of the supported Azure DevOps Services collations. See more details at https://aka.ms/AzureDevOpsImportCollations

此警告 并不意味着 无法导入集合。

此警告要求你确认接受警告。 接受警告后，数据迁移工具可以继续导入准备。

将非支持排序规则导入 Azure DevOps Services 时，排序规则将转换为受支持的排序规则。 虽然此转换通常没有问题，但导入或导入失败后可能会出现意外结果。

例如，客户可能会注意到包含非英语字符的字符串的不同顺序。 导入后，“é”等非英语字符可能等效于英语“e”。 导入具有非支持排序规则的集合时，请务必完成并验证试运行导入。

没有本机支持，没有 Internet 连接

如果数据迁移工具无法连接到 Internet，则无法验证排序规则的转换。 这只是一条警告，因此可以继续迁移过程。 但是，运行 prepare 命令时，需要 Internet 连接，此时会验证排序规则转换。

The collections database's collation '{collation}' is not natively supported in Azure DevOps Services. It could not be validated that the collation can be converted during import to a supported Azure DevOps Services collation, as there was no internet connection. Please run the command again from a machine with an internet connection. See more details at https://aka.ms/AzureDevOpsImportCollations

不支持的数据库排序规则

通常，可以在导入时将非支持排序规则转换为受支持的排序规则。 但是，某些排序规则无法转换。 如果集合使用这些排序规则之一，将收到以下 错误消息 。

The collection database's collation '{collation}' is not supported for import to Azure DevOps Services. It will need to be changed to a supported collation before it can be imported. See more details at https://aka.ms/AzureDevOpsImportCollations

若要继续，需要将 集合的排序 规则更改为 Azure DevOps Services 上受支持的排序规则之一。

更正标识错误

修复迁移前的标识错误，以防止出现问题。 旧 TFS 操作在新 Azure DevOps Server 上无效时很少发生。 例如，某些用户不再位于有效的用户组中。

以下部分提供了解决最常见的标识错误的指南。

ISVError：100014

此错误表示系统安全组中缺少权限。 例如，你创建的每个集合都有 Project Collection Valid Users 和 Project Collection 管理员istrators 组。 系统默认创建它们。 这些组不支持编辑其权限。

此错误表示一个或多个组缺少预期具有的权限。 若要解决此错误，请使用 TFSSecurity.exe 命令将预期权限应用于已标记的系统组。 第一步是确定 需要运行的 TFSSecurity 命令（s）。

项目集合有效用户错误消息

检查突出显示的数据迁移工具的错误消息。 如果标记的组以“0-0-0-0-3”结尾，如以下示例中所示，则需要修复项目集合有效用户组缺少的权限。

运行以下命令，将范围替换为错误消息中的作用域并指定集合 URL。

TFSSecurity.exe /a+ Identity "{scope}\\" Read sid:{Group SID} ALLOW /collection:{collectionUrl}

从错误消息中确定范围和组安全 ID（SID）。

ISVError:100014 Missing permission for group:Microsoft.TeamFoundation.Identity;S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-3 for scope:397c326b-b97c-4510-8271-75aac13de7a9. Expected:1 and Actual:0 

最后一个命令如下所示：

TFSSecurity.exe /a+ Identity "397c326b-b97c-4510-8271-75aac13de7a9\\" Read sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-3 ALLOW /collection:https://localhost:8080/defaultcollection

Project Collection 管理员istrators 错误消息

仔细检查突出显示的数据迁移工具的错误消息。 如果标记的组以“0-0-0-0-0-1”结尾，如以下示例中所示，则需要修复 Project Collection 管理员istrators 组缺少的权限。 针对 TFSSecurity.exe运行以下命令，将范围替换为错误消息中的作用域并指定集合。

TFSSecurity.exe /a+ Identity "{scope}\\" Read sid:{Group SID} ALLOW /collection:{collectionUrl}

TFSSecurity.exe /a+ Identity "{scope}\\" Write sid:{Group SID} ALLOW /collection:{collectionUrl}

TFSSecurity.exe /a+ Identity "{scope}\\" Delete sid:{Group SID} ALLOW /collection:{collectionUrl}

TFSSecurity.exe /a+ Identity "{scope}\\" ManageMembership sid:{Group SID} ALLOW /collection:{collectionUrl}

在以下示例中，从错误消息中获取范围和组 SID ，并将其添加到前面的命令。

ISVError:100014 Missing permission for group:Microsoft.TeamFoundation.Identity;S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 for scope:0c7c2216-fa4b-4107-a203-82b324a147ef. Expected:15 and Actual:0 

最后一个命令如下所示：

TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" Read sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 ALLOW /collection:https://localhost:8080/defaultcollection

TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" Write sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 ALLOW /collection:https://localhost:8080/defaultcollection

TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" Delete sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 ALLOW /collection:https://localhost:8080/defaultcollection

TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" ManageMembership sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 ALLOW /collection:https://localhost:8080/defaultcollection

需要更正多个错误时，建议创建批处理文件以自动执行命令。 执行命令后，需要重新运行数据迁移 验证 工具以验证解决方法。 如果某些错误仍然存在，请联系 Azure DevOps Services 客户支持。

ISVError：300005

ISVError：300005指示非组标识是每个人组的成员，更通常称为“有效用户组”。 有效用户组是为所有项目和集合定义的默认组。 这些组不可编辑。 它们旨在仅包含其他 Azure DevOps 权限或安全组作为成员。 此错误表示 Active Directory （AD） 组或用户标识在有效用户组中具有直接成员身份。

重要

在运行以下命令解决此错误之前，请确保已备份集合和配置数据库。

由于无法直接编辑有效用户组，因此需要针对配置数据库运行 SQL 语句来删除有问题的标识并更正无效的成员身份。 仔细检查数据迁移工具突出显示的错误消息。 复制 ，GroupSidMemberId并ScopeId根据需要将这些值放入以下命令中。

DECLARE @p6 dbo.typ_GroupMembershipTable

INSERT into @p6 values('{GroupSid}','Microsoft.TeamFoundation.Identity','{MemberId}',0)
 
EXEC prc_UpdateGroupMembership @partitionId=1,@scopeId='{ScopeId}',@idempotent=1,@incremental=1,@insertInactiveUpdates=0,@updates=@p6,@eventAuthor='9EE20697-5343-43FC-8FC5-3D5D455D21C5',@updateGroupAudit=0

以下示例列出了 ISVError 的示例：从数据迁移工具300005消息。

ISVError:300005 Unexpected non group identity was found to have direct membership to everyone group. GroupSid:S-1-9-1551374245-3746625149-2333054533-2458719197-2313548623-0-0-0-0-3, MemberId:76050ddf-4fd8-48c4-a1ff-859e44364519, ScopeId:7df650df-0f8b-4596-928d-13dd89e5f34f

如果错误消息列出了一个 MemberSid，则需要从配置数据库中的dbo.tbl_Identity表中获取 MemberID 该表。 然后，可以使用该 MemberIDID 查找 GUID MemberSid。

ISVError:300005 Unexpected non group identity was found to have direct membership to everyone group. GroupSid:S-1-9-1551374245-3746625149-2333054533-2458719197-2313548623-0-0-0-0-3, MemberSid:System.Security.Principal.WindowsIdentity;S-1-5-21-124525095-708259637-1543119021-1737349, ScopeId:7df650df-0f8b-4596-928d-13dd89e5f34f

DECLARE @MemberId uniqueidentifier 

SET @MemberId = (Select Id from dbo.tbl_Identity where Sid ='S-1-5-21-124525095-708259637-1543119021-1737349');

SELECT @MemberId

复制 GroupSidSQL MemberId命令，并将其 ScopeId 复制到 SQL 命令中。

DECLARE @p6 dbo.typ_GroupMembershipTable

INSERT into @p6 values('S-1-9-1551374245-3746625149-2333054533-2458719197-2313548623-0-0-0-0-3','Microsoft.TeamFoundation.Identity','76050ddf-4fd8-48c4-a1ff-859e44364519',0)
 
EXEC prc_UpdateGroupMembership @partitionId=1,@scopeId='7df650df-0f8b-4596-928d-13dd89e5f34f',@idempotent=1,@incremental=1,@insertInactiveUpdates=0,@updates=@p6,@eventAuthor='9EE20697-5343-43FC-8FC5-3D5D455D21C5'

针对 Azure DevOps Server 配置数据库运行已完成的命令。 对每个 ISVError 重复此命令：报告300005实例。 可以将具有相同范围 ID 的错误批处理到单个命令中。 执行命令后，重新运行数据迁移工具将再次验证以确保已更正错误。 如果错误仍然存在，请联系 Azure DevOps Services 客户支持。

重要

若要解决这些错误，必须附加集合。

如果在运行命令时收到 -1 结果，请确保生成错误的集合数据库附加到 Azure DevOps Server 实例，并在配置数据库上运行该命令。

Microsoft Entra 超时异常

在极少数情况下，运行数据迁移工具 prepare 命令时，可能会收到 Microsoft Entra 超时错误。

Exception Message: Request failed (type AadGraphTimeoutException)

此错误表示向 Microsoft Entra ID 发出的请求，以查找集合中用户的匹配 Microsoft Entra 标识超时。通常，可以通过等待在一天不太繁忙的时间运行 准备 命令（例如在常规工作时间之后）来解决此错误。

若要进行故障排除，请从 准备 计算机测试 Microsoft Entra ID 连接。 按照以下步骤从 Microsoft Entra ID 获取用户信息。

在提升模式下打开 PowerShell，并将以下命令中的“”someone@somecompany.com替换为 Microsoft Entra 用户标识。

# Install the Microsoft Graph PowerShell module - ensuring to select Yes to All
Install-Module Microsoft.Graph 

# Import Users module
Import-Module Microsoft.Graph.Users

# Connect to Microsoft Entra and use your Microsoft Entra ID credentials (someone@somecompany.com) to login when the pop-up appears
Connect-MgGraph  -Scopes 'User.Read.All'

# Try to retrieve information on a user from your Microsoft Entra
Get-MgUser -Filter "UserPrincipalName eq 'someone@somecompany.com'"

如果步骤失败或找不到用户，检查准备计算机与 Microsoft Entra ID 之间的连接。 运行网络跟踪，准备查看网络是否阻止调用。 否则，请联系Azure 支持。 检查日志文件中是否有用户信息。

Number of active users is {Number of Users}.

如果活动用户数超过 50,000，则映射的标识量可能需要超过超时限制提供的时间。 检查集合中是否包含大型组，例如“每个人”组。 如果可能，请删除这些组，然后重试。 如果仍无法解决此错误，请联系 Azure DevOps Services 客户支持。

更正进程错误

有关解决常见进程错误的详细信息，请参阅单独的 “进程模板 ”页。

更正字段验证错误

VS403310

检测到集合文件中不一致时，可能会出现以下错误消息。 如果遇到此错误，请联系客户支持。

VS403310: An inconsistency was detected in some of the files in the collection.

VS403442

本地集合和 Azure DevOps Services 系统字段之间有时会发生字段名称冲突。

In order to migrate successfully, you must rename field *{TFSfieldReferenceName}*. Given name *{TFSfieldName}* is reserved for field *{VSTSfieldReferenceName}*.

若要解决此错误，请更改集合字段的名称。 从 witadmin 使用 witadmin changefield 命令。

witadmin changefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName /name:newFieldName

VS403443

以下错误指示本地集合与特定 Azure DevOps Services 字段之间存在字段名称冲突。

In order to migrate successfully, you must rename field *{TFSfieldReferenceName}* to *{VSTSfieldName}*. Given name for *{TFSfieldReferenceName}* is *{TFSfieldName}*

若要解决此错误，请使用 witadmin changefield 命令。 有关详细信息，请参阅 witadmin。

witadmin changefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName /name:VSTSfieldName

VS403444

以下错误指示本地集合与 Azure DevOps Services 之间存在字段类型冲突。

使用 witadmin，只能更改 HTML 或 PlainText 字段的数据类型。

In order to migrate successfully, you must set type of field *{TFSfieldReferenceName}* to *{Type}*. Given type for *{TFSfieldReferenceName}* is *{collectionType}*.

如果字段类型为 HTML 或 PlainText，则可以将其类型更改为所需类型。

witadmin changefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName  /type:PlainText | HTML

注意

如果字段类型与 HTML 或 PlainText 不同，并且字段数据不重要，或者字段未在任何项目中使用，则建议删除该字段。

witadmin deletefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName

重要

删除字段会导致整个集合中的字段数据丢失。

更正导入错误

导入期间发生的失败分为两类之一： 验证失败 和 导入失败。

验证失败

验证失败意味着导入未启动。 数据迁移工具尝试对导入进行排队，但出现错误。 导入请求无效。 修复错误消息，然后再次尝试导入。

VS403254

不支持为 Azure DevOps Services 导入输入的区域。

VS403254: Region {0} might not be used for the Import, it is not a supported region.

打开导入规范文件并更新你为该区域提供的正确短名称 的区域。

VS403249

已选择团队的组织名称已被现有组织使用。 所有 Azure DevOps Services 导入都会进入在导入时创建的新组织。

VS403249: The organization {0} already exists. Please select a different name and try the import again.

选择其他组织名称，并在重试导入之前更新导入规范文件。

VS403250 & VS403286

DACPAC 不是基于分离的集合生成的。

VS403250: The dacpac is not a detached Azure DevOps Server Collection database.

VS403286: The dacpac is from a Azure DevOps Server Configuration database. You must use a detached Azure DevOps Server Collection database.

分离 集合数据库并再次生成 DACPAC。

VS403243

无法使用提供的 SQL 连接ion String 与数据库建立连接。

VS403243: Unable to connect to the database using the provided SQL Connection String {0}.

查看提供的参数以确保它们正确无误，然后重试。

VS403260 & VS403351

未分离集合数据库。

VS403260: The database is not detached.

VS403351: The DACPAC or source database is missing an expected table. It's possible that the database was not correctly detached from Azure DevOps Server.

分离 集合数据库并重试导入队列。

VS403261

连接字符串必须加密，否则密码会以明文形式发送。

VS403261: The SQL connection string must use encryption.

将 Encrypt=true 添加到 SQL 连接字符串。

VS403262

连接字符串必须使用 SQL 身份验证。

VS403262: The SQL connection string must use SQL Authentication, Integrated Authentication is not supported.

将集成安全性=False 添加到 SQL 连接字符串。

VS403263

SQL 登录用户帐户没有所需的数据库角色。

VS403263: The User ID {0} must be member of the database role {1}.

确保为登录的用户帐户分配了“TF标准版XECROLE”角色。

注意

使用 sp_addrolemember 添加到 TFSEXECROLE 现有 SQL 登录名时存在已知问题。 在关闭使用该标识的所有打开连接之前，不会应用角色成员身份。 如果收到VS403263错误，并且已确认标识具有该角色，建议为导入创建新的标识。 有关如何创建新的准备用于导入的 SQL 登录名的详细信息，请参阅 导入大型集合。

VS403264

连接字符串不指向 Azure DevOps Server 集合数据库。

VS403264: The database is not a Azure DevOps Server Collection database, it cannot be used for import.

验证或更正连接字符串指向集合数据库。

VS40325

Azure DevOps Server 更新已将文件迁移作业排队。 在完成此作业之前，无法执行导入。 此作业的完成时间取决于集合的大小。

VS403255: The collection cannot be imported due to an ongoing post upgrade job. Please wait and try again later

可以通过对集合数据库运行以下查询来跟踪作业进度：

SELECT  COUNT (*) as remaining_files_to_migrate
FROM    tbl_FileReference
WHERE   PartitionId > 0
        AND MigrateFileId IS NOT NULL

迁移剩余的文件数为零后，可以运行数据迁移工具。

VS403282

源位置值中存在新的行字符。 从 Windows 控制台复制 SAS 密钥后，此字符可能保持不变。

VS403282: The source location parameter contains a new line character. Please ensure the SAS key is defined on a single line in the import specification file.

删除换行符，然后重试。

VS403271

导入文件和 DACPAC 不在 所需的 Azure 区域中，无法完成目标 Azure DevOps Services 区域的导入。

VS403271: It appears that your DACPAC was uploaded to East US. It's required that customers targeting Central US for import put their DACPACs in Central US. Please move your DACPAC to Central US and requeue the import.

在所需区域中创建新的 Microsoft Azure 存储帐户 并复制文件。 以下示例演示如何使用 AzCopy 复制数据。

AzCopy.exe /Source:https://accountSCUS.blob.core.windows.net/mycontainer /SourceKey:"primary access key" /Dest:https://accountCUS.blob.core.windows.net/mycontainer /DestKey:"primary access key" /S

VS403316

集合中的某些 Team Foundation 版本控制 （TFVC） 文件中检测到不一致。

VS403316: An inconsistency was detected in some TFVC files for this collection. The inconsistency needs to be corrected prior to running an import to Azure DevOps Services. Please reach out to https://aka.ms/AzureDevOpsImportSupport for assistance with addressing this issue.

使用 Azure DevOps Services 客户支持。 打开支持票证，并与你合作解决错误。

VS403366

数据迁移工具无法连接到 SQL Azure VM。

VS403366: A problem occurred while attempting to connect to your database. Please verify that your connection string is correct and that all required IP addresses for Azure DevOps Services have been provided exceptions for your machines firewall.

List of Azure DevOps Services IPs:

验证是否已在连接字符串中正确输入信息，以及是否可以连接到 VM。

错误消息列表的 IP 适用于 Azure DevOps Services。 Azure DevOps Services IP 可以在部署期间暂时更改。 将它们添加到防火墙例外，然后再次尝试排队导入。 有关 IP 地址列表，请参阅 “导入大型集合”，仅限制对 Azure DevOps Services IP 的访问

VS403373

数据迁移工具不支持导入 SAME 集合的多个副本。 但是，它确实支持导入集合的拆分副本。 更改 DataImportCollectionID 的 GUID。

在 SQL Server Management Studio （SSMS）中，打开尚未导入的拆分副本的扩展属性。 将新生成的 GUID 添加到“TFS_DATAIMPORT_COLLECTIONID”属性。 然后重新运行 准备 命令，并使用新的 import.json 文件对导入进行排队。

VS403379

数据导入失败，因为在此集合中找到的一个或多个项目位于软删除阶段。 在运行数据导入之前，还原软删除的项目或将其永久删除。 有关详细信息，请参阅 “删除项目”。

VS403379: Data import will fail as one or more projects found in this collection are in the soft-deleted stage. Please restore the soft-deleted project(s) or delete them permanently before running the data import.

验证运行数据迁移工具的集合是否具有软删除阶段的项目。 删除项目后，它将保持软删除状态 28 天，在此期间可以还原已删除的项目。 可以了解如何在 还原项目中还原已删除的项目。 如果项目位于软删除阶段，请在运行数据导入之前将其完全删除或还原。

导入失败

导入失败意味着导入已排队，但未完成。 排队导入的人员会收到失败的电子邮件通知。 大多数时候，此电子邮件包括失败的原因。 如果这样做，请使用电子邮件和此页面中提供的故障排除步骤来解决错误，然后重试导入。

如果错误更为复杂，则收到的电子邮件提供有关如何提交 客户支持案例的说明。 提交客户支持案例后，团队必须通过使 Azure DevOps Server 实例重新联机并重新附加集合来回滚。 然后，贵团队成员即可继续工作。 建议不要在导致问题解决的失败之前再次尝试导入。

相关文章

• 验证和导入
• 导入后
• 删除项目