VSTS Git Fetch Failed with Exit Code 128: Troubleshooting Hosted Agent Issues After New Project Setup

Setting up a new project in Azure DevOps (formerly VSTS) is an exciting step—whether you’re migrating to the cloud, starting a fresh initiative, or onboarding a new team. However, the journey from project creation to a working pipeline can hit roadblocks, and one common frustration is the "Git fetch failed with exit code 128" error when using Microsoft-hosted agents.

This error typically occurs during pipeline execution when the hosted agent attempts to clone or fetch your Git repository but encounters a critical issue. Exit code 128 is Git’s generic "fatal error" code, masking underlying problems like authentication failures, permission issues, or misconfigured repository settings. For new projects, this error often stems from oversights in setup—such as missing permissions for the build service, typos in repository URLs, or incomplete access configurations.

In this blog, we’ll demystify this error, break down its root causes, and provide a step-by-step troubleshooting guide tailored to Microsoft-hosted agents in newly set up Azure DevOps projects. By the end, you’ll have the tools to diagnose and resolve the issue, ensuring your pipelines run smoothly.

Table of Contents#

  1. Understanding Git Exit Code 128
  2. Why Hosted Agents Fail in New Projects
  3. Step-by-Step Troubleshooting
  4. Common Scenarios and Fixes
  5. Prevention Tips for New Projects
  6. Conclusion
  7. References

Understanding Git Exit Code 128#

Before diving into troubleshooting, let’s clarify what exit code 128 means in Git. Git uses exit codes to communicate success or failure:

  • 0: Success.
  • Non-zero codes: Failures (e.g., 1 for general errors, 127 for command not found).

Exit code 128 is Git’s catch-all for fatal errors—critical issues that prevent the command (e.g., git fetch, git clone) from completing. The actual cause is hidden in the error message伴随 the exit code. For example:

fatal: unable to access 'https://dev.azure.com/MyOrg/MyNewProject/_git/MyRepo/': The requested URL returned error: 403

Or:

fatal: repository 'https://dev.azure.com/MyOrg/WRONGProject/_git/MyRepo/' not found

In the context of Microsoft-hosted agents, this error almost always relates to the agent’s inability to access the repository—either due to misconfiguration, missing permissions, or network barriers.

Why Hosted Agents Fail in New Projects#

Microsoft-hosted agents are managed by Azure DevOps and run in Microsoft’s cloud environment. They come preconfigured with tools like Git, SDKs, and build utilities, but they rely on proper project setup to access your repository. New projects are prone to 128 errors because:

  • Incomplete Permissions: The "Build Service Account" (used by hosted agents) may not have access to the new repository.
  • Typos in Repository URLs: New projects often involve manual URL entry, increasing the risk of typos (e.g., misspelled organization or project names).
  • Uninitialized Repositories: A newly created repo with no commits or branches can cause git fetch to fail.
  • Overlooked Authentication: If using personal access tokens (PATs) or SSH, misconfiguration (e.g., expired PATs) blocks access.

Step-by-Step Troubleshooting#

Let’s walk through diagnosing and resolving the error, starting with the most common causes.

3.1 Check the Full Error Log#

The first step is to inspect the pipeline logs for the exact fatal message伴随 exit code 128. This narrows down the root cause.

How to access logs:

  1. Go to your Azure DevOps project → Pipelines → Select the failed pipeline run.
  2. Click Logs (tab at the top).
  3. Expand the "Checkout" or "Fetch" step (e.g., "Initialize job" or "Checkout MyRepo").

Look for lines like:

  • fatal: Authentication failed for...: Points to auth/permissions.
  • fatal: repository ... not found: Indicates a URL typo.
  • fatal: unable to access ... 403 Forbidden: Permissions issue.

3.2 Verify Repository Permissions for the Build Service Account#

Hosted agents use the Project Collection Build Service Account to access repositories. By default, this account has limited permissions in new projects—often none, unless explicitly granted.

How to check/grant permissions:

  1. Go to your Azure DevOps project → Repos → Repositories.

  2. Select your repository → Click ... (ellipsis) → Security.

  3. In the "Search users and groups" field, enter:

    • Project Collection Build Service (<YourOrganizationName>) (e.g., Project Collection Build Service (MyOrg)).

  4. Ensure the account has at minimum:

    • Read permission (to fetch code).
    • Contribute permission (if the pipeline pushes changes back to the repo).

    If the account is missing, click Add, search for it, and grant the required permissions.

Note: For organization-scoped pipelines, use Organization Build Service (<YourOrganizationName>) instead.

3.3 Validate the Repository URL#

A typo in the repository URL is a frequent culprit. Hosted agents use the URL defined in your pipeline (e.g., in azure-pipelines.yml or the classic editor).

How to verify:

  1. In your pipeline definition, check the repository field. For YAML pipelines: 
    resources:  
  repositories:  
    - repository: MyRepo  
      type: git  
      name: MyNewProject/MyRepo  # Ensure "MyNewProject" matches your project name  
      ref: main
  2. Compare the URL to the repo’s actual URL:
    • Go to Repos → Files → Click Clone → Copy the HTTPS URL (e.g., https://dev.azure.com/MyOrg/MyNewProject/_git/MyRepo).
    • Ensure the pipeline’s URL matches (no missing slashes, correct org/project names).

3.4 Inspect Authentication Mechanisms#

Hosted agents authenticate to Azure DevOps repos using one of two methods:

3.4.1 Default: Build Service Identity#

By default, hosted agents use the Project Collection Build Service Account (authenticated via Azure AD). This works if the account has repo permissions (see 3.2).

3.4.2 Personal Access Tokens (PATs) or SSH#

If you explicitly configured a PAT or SSH key (e.g., for external repos), ensure:

  • PAT Validity: The PAT hasn’t expired and has the Code (Read) scope.
  • SSH Keys: The agent has access to the private key (unlikely for hosted agents, as they’re ephemeral).

Fix for PAT issues:

  • Generate a new PAT with Code (Read) scope: Azure DevOps → User Settings → Personal access tokens.
  • Update the pipeline to use the new PAT (e.g., in service connections).

3.5 Rule Out Network or Firewall Restrictions#

Microsoft-hosted agents run in Azure’s public cloud. If your repository is:

  • In Azure DevOps: It’s publicly accessible to hosted agents (no network issues).
  • On-Premises or Private: Hosted agents can’t access it unless you use a self-hosted agent with VPN/ExpressRoute.

If your repo is in Azure DevOps but you still see network-related errors (e.g., SSL certificate problem), check for:

  • Self-Signed Certificates: Hosted agents don’t trust internal CAs. Use public certificates or a self-hosted agent.
  • Azure Policy Restrictions: Rare, but org-level policies blocking cross-region access could interfere.

3.6 Update the Hosted Agent Image#

Older hosted agent images may have outdated Git versions or dependencies causing 128 errors. Microsoft regularly updates images (e.g., ubuntu-latest, windows-latest).

How to update:
In your pipeline YAML, ensure you’re using the latest image:

pool:  
  vmImage: 'ubuntu-latest'  # or 'windows-latest', 'macos-latest'

Check Microsoft’s hosted agent docs for the latest image names.

Common Scenarios and Fixes#

Let’s apply the above steps to real-world scenarios.

Scenario 1: Missing Permissions for the Build Service Account#

Error Log:

fatal: unable to access 'https://dev.azure.com/MyOrg/MyNewProject/_git/MyRepo/': The requested URL returned error: 403

Diagnosis: The Build Service Account lacks Read access to the repo.

Fix:

  1. Go to Repo → Security → Add Project Collection Build Service (MyOrg).
  2. Grant Read permission → Save.
  3. Re-run the pipeline.

Scenario 2: Typos in the Repository URL#

Error Log:

fatal: repository 'https://dev.azure.com/MyOrg/MyNewProject/_git/MyRepo-TYPO/' not found

Diagnosis: The repo name in the URL has a typo (MyRepo-TYPO instead of MyRepo).

Fix:

  1. In the pipeline YAML or classic editor, correct the repo name.
  2. Validate the URL against the repo’s clone URL (from Repos → Clone).

Scenario 3: Empty or Uninitialized Repository#

Error Log:

fatal: Couldn't find remote ref refs/heads/main

Diagnosis: The repo has no commits or branches (e.g., created but never pushed to).

Fix:

  1. Clone the repo locally → Add a file (e.g., README.md) → Commit and push: 
    git clone https://dev.azure.com/MyOrg/MyNewProject/_git/MyRepo  
cd MyRepo  
echo "# My Repo" > README.md  
git add .  
git commit -m "Initial commit"  
git push origin main
  2. Re-run the pipeline.

Prevention Tips for New Projects#

To avoid exit code 128 in future new projects:

  1. Automate Permissions: Use Azure DevOps REST APIs or Azure CLI to grant the Build Service Account Read access to new repos on creation.
    Example CLI command:

    az devops security permission update \  
  --org https://dev.azure.com/MyOrg \  
  --id 2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87 \  # Repo security namespace ID  
  --subject "Project Collection Build Service (MyOrg)" \  
  --token "$PROJECT_ID/$REPO_ID" \  # Get IDs via az devops project show/repo show  
  --allow-bit 1  # 1 = Read permission

  2. Use Repository Picker: In the pipeline editor, use the "Select a repository" picker instead of manual URL entry to avoid typos.

  3. Initialize Repos with a Commit: Always push an initial commit (e.g., README.md) when creating a new repo.

Conclusion#

Exit code 128 in Microsoft-hosted agents after new project setup is rarely a mystery—it’s almost always due to misconfigured permissions, typos, or uninitialized repos. By following the troubleshooting steps above—starting with checking logs, verifying permissions, and validating the repo URL—you can resolve the issue quickly.

Remember: Hosted agents rely on the "Build Service Account" for access, so ensuring this account has Read permissions is critical. With proactive setup (e.g., automating permissions, initial commits), you can avoid this error altogether.

References#

2026-01