Troubleshooting Common Issues

NuGet errors when installing or upgrading Xchange.Connector.CLI

Symptoms

Similar error message indicating the problematic NuGet package source may appear in the shell used to install the Xchange.Connector.CLI dotnet tool:

Unhandled exception: NuGet.Protocol.Core.Types.FatalProtocolException: 
Unable to load the service index for source https://pkgs.dev.azure.com/.../nuget/v3/index.json.

Common Causes

• Misconfigured NuGet configuration using dotnet.exe (.NET core)
• Missing NuGet configurations using dotent.exe (.NET core)
• IDE credential configurations conflicting with dotnet.exe NuGet configurations

NuGet's behavior is driven by the accumulated settings in one or more NuGet.Config files of your development environment. For more documentation on NuGet behavior, reference Common NuGet configuration.

Your connector repository should contain a nuget.config file with the github-trimble-xchange source and the location of the Xchange authenticated feed.

Verify registered NuGet sources for the current directory:

dotnet nuget list source

The resulting output of this command lists the applied NuGet sources in the context of the current working directory which the command was run.

Solution: github-trimble-xchange source is missing

• Verify your current working directory is your local connector repository
• Add or update the following nuget.config to the root of your connector repository:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="nuget.org"
            value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
        <add key="github-trimble-xchange"
            value="https://nuget.pkg.github.com/trimble-xchange/index.json" />
    </packageSources>
</configuration>

Be sure to include the repository-level nuget.config into source control.

Solution: Multiple package sources with https://nuget.pkg.github.com/trimble-xchange/index.json

• Ensure the project nuget.config contains the <clear /> node to clear applied user NuGet configurations
• Identify the incorrect source name and remove using the dotnet CLI

dotnet nuget remove source <incorrect source name>

Solution: Missing credentials for github-trimble-xchange

• Do not add package source credentials manually to the project nuget.config, this will leak secrets into source control if committed
• Use the dotnet CLI to add your credentials to your user NuGet configuration

dotnet nuget update source github-trimble-xchange -u <username> -p <pat> \
    --store-password-in-clear-text

Addtional references for consuming packages from authenticated feeds can be found here:

• Authenticating with a personal access token (GitHub)
• Consuming packages from authenticated feeds (Microsoft Learn, cross platform)
• Authenticating feeds with nuget.exe credential providers (Microsoft Learn, nuget.exe)
• Authenticating feeds in Visual Studio with NuGet credential provider (Visual Studio)
• Credential providers for private NuGet feeds (Rider)
• Common NuGet configurations

---

Xchange.Connector.CLI is not working with my connector

Symptoms

Similar error messages when executing the xchange commands:

Could not execute because the specified command or file was not found.

The current command could not be fully resolved...

settings.json file could not be found at path...

An error occurred while initializing...

Common Causes

• The .NET tool is not installed globally
• You were working with a pre-release version of the .NET tool
• A new version of the .NET tool is available
• dotnet tool are not included in your PATH
• Your current working directory is not the Connector project of your repository

Solution: Install .NET tool globally

Verify global .NET tool installation:

dotnet tool list --global

To install the .NET tool globally:

dotnet tool install xchange.connector.cli --global

Solution: Outdated pre-release or stable version

Upgrade your .NET installation to latest stable version:

dotnet tool update xchange.connector.cli --global

If you connector requires a specific version:

dotnet tool uninstall xchange.connector.cli

dotnet tool install xchange.connector.cli \
    --global --version <target version>

If you are an early adopter and your connector is targeting a pre-release:

dotnet tool uninstall xchange.connector.cli

dotnet tool install xchange.connector.cli \
    --global --prerelease --version <target prelease version>

Additional references for .NET tool usage issues:

• Install Guide
• Troubleshoot .NET tool usage issues

---

GitHub access to connector repository (Trimble Users)

Symptoms

• You cannot clone your provisioned repository
• You cannot find your provisioned repository within the trimble-xchange organization

Common Causes

• You do not belong to the Trimble GitHub organization
• Your GitHub account was not added to the correct team
• Your GitHub team does not have the correct permissions to work with your connector

Solution

Connect with your Xchange contact person and validate your provisioned environment.

---

Key violations or duplicate records when testing or developing locally

Symptoms

• When running a cache writer a key violation error message is output
• When running a cache writer you encounter duplicate records returned

Common Causes

• Change detection in your local environment is in a bad state because of a data object key was modified
• The change detection database in your local environment has become corrupted

Solution: Clean change detection for your local environment

1. Build the project.
2. Run xchange test init to set up the environment and generate testsettings.json.
3. Reset the environment with xchange test reset.
4. If issues persist, delete bin and obj directories, then repeat the initialization steps.

Whenever modifying data objects, rerun xchange test init to update testsettings.json. If altering existing data objects, execute xchange test reset first to avoid discrepancies in the change detection database.

Additional references for local testing:

• Testing Guide

---

Build or deployment failures to Xchange Test Environment

Symptoms

• Initial deployments to the test environment fail
• Deployments to the test environment beyond the first accepted PR fail

Common Causes

• The connector is in a provisioning state
• The settings.json targets an incorrect urlPart

Solution: Intial deployment failure

Any deployment failures observed in GitHub actions prior to the first accepted PR may fail deployment to the test environment as the connector in a provisioning stage. These failures can be ignored.

Solution: Deployments after the first accepted PR fail

Verify that the settings.json file is correctly configured for your connector. If you need additional support, connect with your Xchange contact person.

---

Changes have not deployed to production environment

Symptoms

• Expected changes are not applied in Xchange production environment

Common Causes

• Pull requests to main were not approved by Xchange team
• Changes have not yet been released by the Xchange team

Solutions

• Verify your pull request has merged
• Connect with your Xchange contact person and verify a release schedule for your changes