apache/dolphinscheduler · error · IllegalArgumentException

model key must start with runs:/ or models:/

Error message

model key must start with runs:/ or models:/ 

What it means

MlflowParameters.getModelKeyName() builds a Docker image name from the MLflow model key. It only supports keys starting with 'runs:/' or 'models:/'; anything else throws IllegalArgumentException('model key must start with runs:/ or models:/ ').

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-mlflow/src/main/java/org/apache/dolphinscheduler/plugin/task/mlflow/MlflowParameters.java:131

    private void getParamsMapForAutoML(HashMap<String, String> paramsMap) {
        paramsMap.put("automl_tool", automlTool);
        paramsMap.put("repo", MlflowConstants.PRESET_AUTOML_PROJECT);
        paramsMap.put("repo_version", MlflowConstants.PRESET_REPOSITORY_VERSION);
    }

    public Boolean isCustomProject() {
        return mlflowJobType.equals(MlflowConstants.JOB_TYPE_CUSTOM_PROJECT);
    }

    public String getModelKeyName(String tag) throws IllegalArgumentException {
        String imageName;
        if (deployModelKey.startsWith("runs:")) {
            imageName = deployModelKey.replace("runs:/", "");
        } else if (deployModelKey.startsWith("models:")) {
            imageName = deployModelKey.replace("models:/", "");
        } else {
            throw new IllegalArgumentException("model key must start with runs:/ or models:/ ");
        }
        imageName = imageName.replace("/", tag).toLowerCase();
        return imageName;
    }

    public String getContainerName() {
        return "ds-mlflow-" + getModelKeyName("-");
    }

    public boolean getIsDeployDocker() {
        if (StringUtils.isEmpty(deployType)) {
            return false;
        }
        return deployType.equals(MlflowConstants.MLFLOW_MODELS_DEPLOY_TYPE_DOCKER);
    }
}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Prefix the model key with 'runs:/' (run artifacts) or 'models:/' (registered model) in the MLflow task parameters.
2. Check the value for typos and exact case: it must start with 'runs:' or 'models:'.
3. For a registered model, register it in the MLflow Model Registry and use its 'models:/name/version' URI.
4. Convert filesystem/S3 paths into a supported MLflow URI or use a different task type.

Example fix

// before
modelKey = "s3://my-bucket/model"
// after
modelKey = "models:/my-model/1"  // or "runs:/<run_id>/model"

if (!(modelKey.startsWith("runs:/") || modelKey.startsWith("models:/"))) {
    throw new IllegalArgumentException("model key must start with runs:/ or models:/");
}

boolean isValidMlflowModelKey(String k) {
    return k != null && (k.startsWith("runs:/") || k.startsWith("models:/"));
}

When it happens

Trigger: deployModelKey is set to a raw path (e.g. 'my/model', 's3://bucket/model', 'dbfs:/...') or a mistyped scheme/case such as 'run:/' or 'Runs:/'.

Common situations: User pastes an unsupported MLflow model URI (s3://, filesystem path) into the MLflow task; typo'd prefix; copying a model path from the MLflow UI without its runs:/ or models:/ prefix.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• MLFlow task params is not valid
• url can not be null
• 10001
• namespace %s does not exist in k8s cluster, please create na
• ID token is missing required claims

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/63b090f472884ddb. Report an issue: GitHub.