Troubleshooting Failure of DevOps Services Import from TFS

Hello Bruce Backman,

The "Object reference not set to an instance of an object" error in Bug.xml during your Azure DevOps Services import from TFS, addressing all your questions and issues.

Fix Validation Command

You used witadmin validatewitd, which isn’t valid (causing error TF212001). The correct command is:

witadmin importwitd /collection:http://msi-tfs2022:8080/tfs/DefaultCollection /p:SPX /f:Bug.xml /v

Since this passed, Bug.xml is locally valid, but Azure DevOps Services applies stricter rules. Re-export to ensure you have the latest version:

witadmin exportwitd /collection:http://msi-tfs2022:8080/tfs/DefaultCollection /p:SPX /n:Bug /f:Bug.xml

Update WebLayout and Remove FORM

You asked if <WebLayout> is deprecated and what defines the form layout if removed. <WebLayout> is not deprecated.it’s required for Azure DevOps Services to define the web form. The <FORM> section in your Bug.xml is for on-premises TFS and should be removed, as it’s ignored in the cloud and may cause errors. Enhance <WebLayout> to include all fields (e.g., Custom.Quality, Custom.TestedBy, Custom.ImplementedBy). Here’s a revised Bug.xml with <FORM> removed and <WebLayout> updated (keeping <FIELDS> and <WORKFLOW> unchanged)

<?xml version="1.0" encoding="utf-8"?>

<witd:WITD application="Work item type editor" version="1.0" xmlns:witd="http://schemas.microsoft.com/VisualStudio/2008/workitemtracking/typedef">

  <WORKITEMTYPE name="Bug">

    <DESCRIPTION>Describes a divergence between required and actual behavior, and tracks the work done to correct the defect and verify the correction.</DESCRIPTION>

    <FIELDS>

      <!-- Your existing FIELDS section -->

    </FIELDS>

    <WORKFLOW>

      <!-- Your existing WORKFLOW section -->

    </WORKFLOW>

    <WebLayout>

      <Page Label="Details" LayoutMode="FirstColumnWide">

        <Section>

          <Group>

            <Control Type="FieldControl" FieldName="System.Title" Label="Title" EmptyText="<Enter title here>" />

            <Control Type="WorkItemClassificationControl" FieldName="System.IterationPath" Label="Iteration" />

            <Control Type="WorkItemClassificationControl" FieldName="System.AreaPath" Label="Area" />

          </Group>

          <Group Label="Steps to Reproduce">

            <Control Type="HtmlFieldControl" FieldName="Microsoft.VSTS.TCM.ReproSteps" Label="Steps to Reproduce" />

          </Group>

          <Group Label="System Info">

            <Control Type="HtmlFieldControl" FieldName="Microsoft.VSTS.TCM.SystemInfo" Label="System Info" />

          </Group>

          <Group Label="Acceptance Criteria">

            <Control Type="HtmlFieldControl" FieldName="Microsoft.VSTS.Common.AcceptanceCriteria" Label="Acceptance Criteria" />

          </Group>

        </Section>

        <Section>

          <Group Label="Status">

            <Control Type="FieldControl" FieldName="System.AssignedTo" Label="Assigned To" />

            <Control Type="FieldControl" FieldName="System.State" Label="State" />

            <Control Type="FieldControl" FieldName="Custom.ImplementedBy" Label="Implemented By" />

            <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.ReviewedBy" Label="Reviewed By" />

            <Control Type="FieldControl" FieldName="Custom.TestedBy" Label="Tested By" />

            <Control Type="FieldControl" FieldName="System.Reason" Label="Reason" />

          </Group>

          <Group Label="Details">

            <Control Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.Effort" Label="Effort" />

            <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Severity" Label="Severity" />

            <Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.BacklogPriority" Label="Backlog Priority" />

            <Control Type="FieldControl" FieldName="Custom.Quality" Label="Quality" />

          </Group>

        </Section>

        <Section>

          <Group Label="Links and Attachments">

            <Control Type="LinksControl" Name="GeneralLinks" Label="Links">

              <LinksControlOptions>

                <LinkColumns>

                  <LinkColumn RefName="System.Id" />

                  <LinkColumn RefName="System.WorkItemType" />

                  <LinkColumn RefName="System.Title" />

                  <LinkColumn RefName="System.AssignedTo" />

                  <LinkColumn RefName="System.State" />

                  <LinkColumn LinkAttribute="System.Links.Comment" />

                </LinkColumns>

                <WorkItemLinkFilters FilterType="includeAll" />

                <ExternalLinkFilters FilterType="includeAll" />

                <WorkItemTypeFilters FilterType="includeAll" />

              </LinksControlOptions>

            </Control>

            <Control Type="AttachmentsControl" Label="Attachments" />

          </Group>

          <Group Label="History">

            <Control Type="WorkItemLogControl" FieldName="System.History" Label="History" />

          </Group>

        </Section>

      </Page>

    </WebLayout>

  </WORKITEMTYPE>

</witd:WITD>

Handle HtmlFieldControl

You asked about HtmlFieldControl deprecation and its replacement. It’s not deprecated and is supported for rich text fields like Microsoft.VSTS.TCM.ReproSteps, Microsoft.VSTS.TCM.SystemInfo, and Microsoft.VSTS.Common.AcceptanceCriteria. Use it in the updated Bug.xml. If the import fails, try FieldControl, though it may limit formatting:

<Control Type="FieldControl" FieldName="Microsoft.VSTS.TCM.ReproSteps" Label="Steps to Reproduce" />

Check logs for HtmlFieldControl errors. Refer to form customization for details.

Check Field Definitions

To identify undefined or obsolete fields (e.g., Custom.TestedBy, Custom.ImplementedBy, Custom.Quality) despite passing validation:

• Verify their existence:

  
    witadmin listfields /collection:http://msi-tfs2022:8080/tfs/DefaultCollection /n:Custom.TestedBy
  
    witadmin listfields /collection:http://msi-tfs2022:8080/tfs/DefaultCollection /n:Custom.ImplementedBy
  
    witadmin listfields /collection:http://msi-tfs2022:8080/tfs/DefaultCollection /n:Custom.Quality
  
  

• If missing, recreate them post-migration in Azure DevOps Services (Process > Fields). Review import logs for field issues.

Test with Default Template

Since the GitHub link for process templates was broken, get a default Bug template from your Azure DevOps Server installation (e.g., C:\Program Files\Azure DevOps Server 2020\Tools\Deploy\ProcessTemplate\Agile\WorkItem Tracking\TypeDefinitions\Bug.xml) or default process templates.

• Backup your Bug.xml.
• Replace it with the default template and run a dry-run import.
• Avoid Data Loss:
  • Document custom field data:

    
        SELECT [System.Id], [Custom.TestedBy], [Custom.ImplementedBy], [Custom.Quality] FROM WorkItems WHERE [System.WorkItemType] = 'Bug'
    
    

  • If the default template succeeds, reintroduce custom fields gradually, testing each change. Recreate fields in Azure DevOps Services if needed and restore data via work item updates.

Access Migration Logs

You noted that status URLs showed “in progress” then 404, blocking dry-run details. Check local logs immediately after a failed import:

%LocalAppData%\TfsMigrator\Logs

Look for errors about fields, controls, or schema to pinpoint the issue.

Retry Import

• Use the updated Bug.xml.
• Rerun the migration:
  1. Validate with TfsMigrator.
  2. Create and upload a new DACPAC.
  3. Start a dry-run import.
• Check logs promptly if it fails.

If problems persist, validate linked work item types (e.g., Task, Test Case). Let me know if you need further assistance!

References:

• WebLayout XML elements
• Form customization
• Default process templates

Questions/comments collected together for easier reference, also found below in context:

• How would I tell if a field is undefined or obsolete? They all pass validation.
• The whole WebLayout section is deprecated??? What defines the form layout if that is removed?
• Where is the deprecation of HtmlFieldControl documented? What can I replace it with in order to preserve functionality?
• Bug.xml I have attached the current bug.xml for your reference
• The link to Microsoft's process template GitHub repository is broken
• If the process template repository link was not broken, how would I avoid data loss when replacing a work item definition with one that does not have our existing fields?

Validate the Exported Bug.xml File

  witadmin validatewitd /collection:http://msi-tfs2022:8080/tfs/DefaultCollection /p:SPX /f:Bug.xml

    TF212001: validatewitd is not a witadmin command. Type 'witadmin' and press Enter for a list of commands.

  witadmin importwitd /collection:http://msi-tfs2022:8080/tfs/DefaultCollection /p:SPX /f:Bug.xml /v

    The work item type is valid.

Manually Inspect the Bug.xml for Deprecated or Invalid References

• How do I tell if fields are undefined or obsolete? They all pass validation.
• Deprecated elements such as <WebLayout>, <Control Type="HtmlFieldControl">, etc.
  • The whole WebLayout section is deprecated??? What defines the form layout if that is removed?
  • Where is the deprecation of HtmlFieldControl documented? What can I replace it with in order to preserve functionality?
• I have attached the current bug.xml for your reference Replace with a Known Working Template for Testing
• The link to Microsoft's process template GitHub repository is broken
• If the process template link was not broken, how would I avoid data loss when replacing a work item definition with one that does not have our existing fields?

Analyze Import Failure Logs Using Correlation ID

• I have attempted to get migration status from both the long link in the import email and the https://dev.azure.com/YOURORG/_migration URL in your message. During and shortly after a failed import, both forms of the URL say a data import is in progress and I should try back later. After a few days , that changes to a 404. I have never been able to access useful status information about any of my dry-run imports.

Hello Bruce Backman,
Please verify the modified comment above. If you need further assistance, please provide the comment.

Hello Bruce Backman,

Following up to see if you have chance to check the previous response and help us with requested information to check and assist you further on this.

Please do not edit/replace your previous replies. That prevents me from referring back to them to see the context for my replies and questions.

Your new replies are very confusing.

Your initial reply suggested looking for "Deprecated elements such as <WebLayout>, <Control Type="HtmlFieldControl">, etc." but your follow up says neither of those is deprecated.

You suggest removing the <FORM> element from bug.xml and leaving <WebLayout>, but <WebLayout> is a child of <FORM>. I tried both removing the <Layout> child of <FORM>, leaving <FORM><WebLayout><WebLayout/><FORM/> and also removing <FORM> altogether leaving <WORKITEMTYPE><WebLayout><WebLayout/><WORKITEMTYPE/> as in your example. Neither of those structures pass validation by witadmin.

Choosing a workitem type less critical than Bug, I compared my current Impediment.xml with the one from the standard Scrum process template, then edited it to align as closely as possible to the standard one. I left the extra fields that were in our definition, verifying that they existed in the current database. I then went through another full dry run import. That dry run failed and still reported a null reference error for impediment.xml.

I commented out all of the extra fields that are in our impediment.xml and not in the standard scrum impediment.xml. Yet another dry run import. It still failed, and still reported a null reference for impediment.xml. So, the idea of using the work item definition from a standard template does not seem to solve whatever the error is.