Skip to content

Troubleshooting Common Issues

The App Xchange team is constantly working to improve the development experience. Many common issues can be resolved or mitigated by making sure you have the latest versions of the CLI, SDK, and Local Testing packages installed, which can conveniently be done with the following commands:

dotnet tool update Trimble.Xchange.Connector.CLI --global

dotnet add package Trimble.Xchange.Connector.SDK

dotnet add package Trimble.Xchange.Connector.SDK.Test.Local

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 Trimble.Xchange.Connector.CLI --global

Solution: Verify project targeting

  • Verify /Connector/Connector.csproj targets the dotnet version you have installed
  • Clear /Connector/bin
  • Install a long term support version: https://dotnet.microsoft.com/en-us/download/dotnet

Solution: Outdated pre-release or stable version

Upgrade your .NET installation to latest stable version:

dotnet tool update Trimble.Xchange.Connector.CLI --global

If your connector requires a specific version:

dotnet tool uninstall Trimble.Xchange.Connector.CLI

dotnet tool install Trimble.Xchange.Connector.CLI \
    --global --version <target version>

If you need a version still in development, either out of necessity or to provide feedback:

dotnet tool uninstall Trimble.Xchange.Connector.CLI

dotnet tool install Trimble.Xchange.Connector.CLI \
    --global --prerelease --version <target prerelease version>

Additional references for .NET tool usage issues:

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 test-settings.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 test-settings.json. If altering existing data objects, execute xchange test reset first to avoid discrepancies in the change detection database.

Additional references for local testing:

Changes have not deployed to production environment

Symptoms

  • Expected changes are not applied in Xchange production environment

Common Causes

  • Connector submission was not approved by Xchange team
  • Changes have not yet been released by the Xchange team

Solutions

  • Verify your submission status with xchange code list
  • Email xchange_build@trimble.com and verify a release schedule for your changes

ERR Extracting Connector metadata was not successful (150).

Symptoms

  • Commands fail on extraction, which is checking for breaking changes.

Common Causes

  • You are not logged in, or permissions have changed.
  • Your key and urlPart in settings.json do not match what has been provisioned to you
  • There is a broader error such as a missing framework or dotnet and .csproj version mismatch

Solutions

  • Confirm you are logged in with xchange logout and xchange login.
  • Check "connectors" in your account on App Xchange and settings.json for an exact key and urlPart match
  • Confirm that connector.csproj targets the .NET version you have installed, ideally the Long Term Support version.
  • Use dotnet run --launch-profile "Direct Run Extraction" to run with additional logging and take action as appropriate