mlflow/mlflow · error · MlflowException

`artifact_path` cannot be specified if `artifact_uri` is spe

Error message

`artifact_path` cannot be specified if `artifact_uri` is specified

What it means

When listing via artifact_uri there is no run to resolve a sub-path against, so passing artifact_path alongside artifact_uri is rejected with INVALID_PARAMETER_VALUE.

Source

Thrown at mlflow/artifacts/__init__.py:136

        artifact_uri: URI pointing to the artifacts, such as
            ``"runs:/500cf58bee2b40a4a82861cc31a617b1/my_model.pkl"``,
            ``"models:/my_model/Production"``, or ``"s3://my_bucket/my/file.txt"``.
            Exactly one of ``artifact_uri`` or ``run_id`` must be specified.
        run_id: ID of the MLflow Run containing the artifacts. Exactly one of ``run_id`` or
            ``artifact_uri`` must be specified.
        artifact_path: (For use with ``run_id``) If specified, a path relative to the MLflow
            Run's root directory containing the artifacts to list.
        tracking_uri: The tracking URI to be used when list artifacts.

    Returns:
        List of artifacts as FileInfo listed directly under path.
    """
    if (run_id, artifact_uri).count(None) != 1:
        raise MlflowException.invalid_parameter_value(
            message="Exactly one of `run_id` or `artifact_uri` must be specified",
        )
    elif artifact_uri is not None and artifact_path is not None:
        raise MlflowException.invalid_parameter_value(
            message="`artifact_path` cannot be specified if `artifact_uri` is specified",
        )

    if artifact_uri is not None:
        root_uri, artifact_path = _get_root_uri_and_artifact_path(artifact_uri)
        return get_artifact_repository(
            artifact_uri=root_uri, tracking_uri=tracking_uri
        ).list_artifacts(artifact_path)

    # Use `runs:/<run_id>/<artifact_path>` to list both run and model (if exists) artifacts
    if run_id and artifact_path:
        return get_artifact_repository(
            artifact_uri=f"runs:/{run_id}", tracking_uri=tracking_uri
        ).list_artifacts(artifact_path)

    store = _get_store(store_uri=tracking_uri)
    artifact_uri = store.get_run(run_id).info.artifact_uri
    artifact_repo = get_artifact_repository(

View on GitHub (pinned to 6a27f2decc)

Solutions

Drop artifact_path and embed the sub-path into artifact_uri
Use run_id + artifact_path instead if listing inside a run
Guard in wrappers: set artifact_path=None whenever artifact_uri is given

Example fix

// before
list_artifacts(artifact_uri="s3://bucket/run/artifacts", artifact_path="model")
// after
list_artifacts(artifact_uri="s3://bucket/run/artifacts/model")

Defensive patterns

Strategy: validation

Validate before calling

if artifact_uri is not None:
    assert artifact_path is None, "embed sub-path in artifact_uri instead"

Try / catch

try:
    infos = mlflow.artifacts.list_artifacts(artifact_uri=uri, artifact_path=sub)
except MlflowException as e:
    if "artifact_path` cannot be specified" in str(e):
        infos = mlflow.artifacts.list_artifacts(artifact_uri=f"{uri.rstrip('/')}/{sub}")
    else:
        raise

Prevention

Treat artifact_uri as fully-resolved: include the sub-path in it
Use run_id + artifact_path when you need path-style listing
Centralize artifact listing in one validated helper

When it happens

Trigger: Calling list_artifacts(artifact_uri="s3://bucket/run/artifacts", artifact_path="model").

Common situations: Shared helper that always forwards artifact_path; converting run_id-based listing code to URI-based without dropping artifact_path.

Related errors

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