Skip to main content

Client-Server Version Compatibility After Upgrades

Angelo Bresci

Area: Deployment

Sub-Area: Version Management

Issue

After upgrading the DataHub server to a new version (e.g., v0.3.13), ingestion execution logs display warnings about client-server version incompatibility, stating that the CLI version is newer than the server version and suggesting a downgrade. However, the release documentation may recommend a different CLI version than what the warning suggests, creating confusion about which version to use.

Common Error Messages:

  • Client version (1.2.0.1) is newer than server version (0.3.13). Please consider downgrading your CLI version.

You Might Be Asking:

  • What CLI version should I use with my server version?
  • Why does the warning suggest downgrading when the release notes say otherwise?
  • Do I need to update my remote executor image when upgrading?
  • What happens if I run mismatched versions?

Solution

Maintain version alignment between the DataHub server and CLI to ensure compatibility and optimal functionality.

Version Compatibility Rules:

General Principle: - Server version and CLI version should be aligned - Exact version matching is recommended - Minor version mismatches are usually tolerated but not guaranteed

Finding the Correct CLI Version:

  1. Check Release Notes:

  2. Server Version to CLI Mapping Examples:

    • Server v0.3.13 → CLI 1.2.0.1
    • Server v0.3.13.2 → CLI 1.2.0.6

Installing Specific CLI Version:


# Uninstall current CLI
pip uninstall acryl-datahub

# Install specific version
pip install acryl-datahub==1.2.0.1

# Verify installation
datahub version

Updating Remote Executor:

The remote executor must use a matching image version:


# values.yaml for Helm deployment
image:
  repository: acryldata/datahub-ingestion
  tag: "v0.3.13.2"  # Match server version

For Terraform or CloudFormation deployments:


# Terraform example
task_definition_image = "acryldata/datahub-ingestion:v0.3.13.2"

Important Notes About Version Warnings:

  • Version mismatch warnings may appear even with compatible versions
  • The warning message text may be incorrect or outdated
  • Trust the release notes over warning messages
  • These are warnings, not errors; functionality typically works with minor mismatches

Patch Release Handling:

For patch releases (e.g., 0.3.13.0 → 0.3.13.2): - Update the image version in configuration files - No Helm chart upgrade required for patch releases - Only the container image tag needs updating - Backward compatibility is maintained within patch versions

Verification After Update:


# Check CLI version
datahub version

# Check server version via API
curl https://your-instance.acryl.io/version

# Or check in the UI footer

Troubleshooting Version Mismatches:

If you experience issues with mismatched versions: 1. Verify server version in UI or API 2. Check CLI version: datahub version 3. Consult release notes for correct pairing 4. Update CLI and remote executor to match 5. Restart any running ingestion jobs

Additional Notes

  • Acryl support explicitly communicates when remote executor updates are required
  • Default CLI versioning is managed by the DataHub team
  • Breaking changes are avoided whenever possible
  • Version compatibility is tested, but exact matching is safest

Related Tickets

  • 4710

Tags: version-compatibility, cli, client-server, upgrade, remote-executor, version-mismatch, deployment, compatibility-warning

Related to

Related articles