mlflow/mlflow · error · TypeError

The `artifact_file` parameter cannot be used in conjunction

Error message

The `artifact_file` parameter cannot be used in conjunction with `key`, `step`, or `timestamp` parameters. Please ensure that `artifact_file` is specified alone, without any of these conflicting parameters.

What it means

MLflow's MlflowClient.log_image() supports two mutually exclusive ways to log an image: a static file via `artifact_file`, or a dynamic chart via `key` (with optional `step`/`timestamp`). Passing `artifact_file` together with any of `key`, `step`, or `timestamp` is ambiguous, so the method raises a TypeError before doing any work.

Source

Thrown at mlflow/tracking/client.py:3238

                client = mlflow.MlflowClient()
                client.log_image(run.info.run_id, image, "image.png")

        .. code-block:: python
            :caption: Legacy artifact file image logging pillow example

            import mlflow
            from PIL import Image

            image = Image.new("RGB", (100, 100))
            with mlflow.start_run() as run:
                client = mlflow.MlflowClient()
                client.log_image(run.info.run_id, image, "image.png")
        """
        synchronous = (
            synchronous if synchronous is not None else not MLFLOW_ENABLE_ASYNC_LOGGING.get()
        )
        if artifact_file is not None and any(arg is not None for arg in [key, step, timestamp]):
            raise TypeError(
                "The `artifact_file` parameter cannot be used in conjunction with `key`, "
                "`step`, or `timestamp` parameters. Please ensure that `artifact_file` is "
                "specified alone, without any of these conflicting parameters."
            )
        elif artifact_file is None and key is None:
            raise TypeError(
                "Invalid arguments: Please specify exactly one of `artifact_file` or `key`. Use "
                "`key` to log dynamic image charts or `artifact_file` for saving static images. "
            )

        import numpy as np

        # Convert image type to PIL if its a numpy array
        if isinstance(image, np.ndarray):
            image = convert_to_pil_image(image)
        elif isinstance(image, Image):
            image = image.to_pil()
        else:

View on GitHub (pinned to 6a27f2decc)

Solutions

Remove `key`, `step`, and `timestamp` arguments when logging a static image with `artifact_file`.
If you need step/timestamp tracking, switch to the dynamic-chart style: pass `key` instead of `artifact_file`.
If wrapping log_image, conditionally forward only the relevant parameter group based on which mode is intended.

Example fix

// before
client.log_image(run_id, img, artifact_file="image.png", step=3)
// after
client.log_image(run_id, img, artifact_file="image.png")

Defensive patterns

Strategy: validation

Validate before calling

if artifact_file is not None and any(a is not None for a in (key, step, timestamp)):
    raise ValueError("Use either artifact_file OR (key, step, timestamp), not both")

Try / catch

try:
    client.log_image(run_id, img, artifact_file="image.png", step=step)
except TypeError as e:
    if "artifact_file" in str(e):
        client.log_image(run_id, img, artifact_file="image.png")
    else:
        raise

Prevention

Pick one logging mode per call site and document it
In wrappers, forward only the parameter group that is populated
Keep step/timestamp usage only with the key-based API

When it happens

Trigger: Calling client.log_image(run_id, image, artifact_file='image.png') while also passing key, step, or timestamp (any non-None value among them). The check is `artifact_file is not None and any(arg is not None for arg in [key, step, timestamp])`.

Common situations: Migrating code from the key-based logging API to file-based logging and leaving a leftover step=0 or timestamp argument; copy-pasting examples of both styles into one call; building a wrapper that forwards all kwargs unconditionally.

Related errors

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