mlflow/mlflow · error · MlflowClientException

Failed to construct request URI for get latest versions.

Error message

Failed to construct request URI for get latest versions.

What it means

makeGetLatestVersions builds the 'model-versions/get-latest-versions' query URI with URIBuilder and wraps any URISyntaxException into MlflowClientException. In practice this fires when building the URI fails, almost always due to illegal characters in a parameter value that URIBuilder cannot encode in this context.

Source

Thrown at mlflow/java/client/src/main/java/org/mlflow/tracking/MlflowProtobufMapper.java:136

  String makeRestoreRun(String runId) {
    RestoreRun.Builder builder = RestoreRun.newBuilder();
    builder.setRunId(runId);
    return print(builder);
  }

  String makeGetLatestVersion(String modelName, Iterable<String> stages) {
    try {
      URIBuilder builder = new URIBuilder("registered-models/get-latest-versions")
              .addParameter("name", modelName);
      if (stages != null) {
        for( String stage: stages) {
          builder.addParameter("stages", stage);
        }
      }
      return builder.build().toString();
    } catch (URISyntaxException e) {
      throw new MlflowClientException("Failed to construct request URI for get latest versions.",
              e);
    }
  }

  String makeUpdateModelVersion(String modelName, String version) {
    return print(UpdateModelVersion.newBuilder().setName(modelName).setVersion(version));
  }

  String makeTransitionModelVersionStage(String modelName, String version, String stage) {
    return print(TransitionModelVersionStage.newBuilder()
            .setName(modelName).setVersion(version).setStage(stage));
  }

  String makeCreateModel(String modelName) {
    CreateRegisteredModel.Builder builder = CreateRegisteredModel.newBuilder()
            .setName(modelName);
    return print(builder);
  }

View on GitHub (pinned to 6a27f2decc)

Solutions

Check the model name and stage strings for illegal characters (spaces, '/', '?', control chars) and sanitize them.
Use a registry-compliant model name (alphanumerics, dashes, underscores, dots).
If the exception persists, capture the chained URISyntaxException (it is attached as the cause) for the exact parse error.
Retry the call with a plain ASCII name to isolate which parameter breaks URI construction.

Example fix

// before
client.getLatestVersions("my model/v2", Lists.newArrayList("Production"));
// after
client.getLatestVersions("my-model-v2", Lists.newArrayList("Production"));

Defensive patterns

Strategy: validation

Validate before calling

static String sanitizeModelName(String name) {
  String trimmed = name == null ? "" : name.trim();
  if (!trimmed.matches("[A-Za-z0-9_.-]+")) {
    throw new IllegalArgumentException("Model name has URI-illegal characters: " + trimmed);
  }
  return trimmed;
}
// use: client.getLatestVersions(sanitizeModelName(rawName), stages)

Type guard

static boolean isUriSafeParam(String value) {
  return value != null && value.matches("[A-Za-z0-9_.\- ]*") && !value.contains("/");
}

Try / catch

try {
  return client.getLatestVersions(modelName, stages);
} catch (MlflowClientException e) {
  if (e.getMessage().contains("Failed to construct request URI")) {
    throw new IllegalArgumentException("Check model name/stage for illegal URI characters: " + modelName, e.getCause());
  }
  throw e;
}

Prevention

Validate model names against [A-Za-z0-9_.-] before any registry call.
Trim whitespace and strip hidden characters when loading names from files/env.
Log the full exception cause (URISyntaxException) to see the exact offending character.
Prefer UTF-8 URL encoding at your own boundary instead of passing raw strings.

When it happens

Trigger: Calling getLatestVersions (via MlflowClient.getLatestVersions/downloadLatestModelVersion) when the resulting URI construction throws URISyntaxException — e.g. model name or stage containing characters the URIBuilder rejects for the request path/parameters.

Common situations: Model names containing spaces, slashes, or other special characters that were never valid registry names; corrupted stage or name strings from config/env; copying names with trailing whitespace or hidden characters from a UI or file.

Related errors

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/81c4284dceacbd62. Report an issue: GitHub.