mlflow/mlflow · error · ExecutionException

Project with docker environment must specify the docker imag

Error message

Project with docker environment must specify the docker image to use via an 'image' field under the 'docker_env' field.

What it means

MLflow raises this ExecutionException when an MLproject file declares docker as its environment but the 'docker_env' section is missing an 'image' key. The image name is required because MLflow builds/tags the project's Docker container from it. Without it, the project cannot be executed with the docker backend.

Source

Thrown at mlflow/projects/docker.py:62

        capture_output=False,
        stdout=subprocess.PIPE,
        stderr=subprocess.STDOUT,
    )
    if prc.returncode != 0:
        joined_cmd = " ".join(cmd)
        raise ExecutionException(
            f"Ran `{joined_cmd}` to ensure docker daemon is running but it failed "
            f"with the following output:\n{prc.stdout}"
        )


def validate_docker_env(project):
    if not project.name:
        raise ExecutionException(
            "Project name in MLProject must be specified when using docker for image tagging."
        )
    if not project.docker_env.get("image"):
        raise ExecutionException(
            "Project with docker environment must specify the docker image "
            "to use via an 'image' field under the 'docker_env' field."
        )


def build_docker_image(work_dir, repository_uri, base_image, run_id, build_image, docker_auth):
    """
    Build a docker image containing the project in `work_dir`, using the base image.
    """
    image_uri = _get_docker_image_uri(repository_uri=repository_uri, work_dir=work_dir)
    client = docker.from_env()
    if docker_auth is not None:
        client.login(**docker_auth)

    if not build_image:
        if not client.images.list(name=base_image):
            _logger.info(f"Pulling {base_image}")
            image = client.images.pull(base_image)

View on GitHub (pinned to 6a27f2decc)

Solutions

Add an 'image' field under 'docker_env' in MLproject, e.g. docker_env: {image: myregistry/myimage:latest}
Verify the MLproject YAML parses as expected (project.docker_env is a dict containing 'image')
If you intend MLflow to build the image, still set a base/tag name for image via docker_env.image

Example fix

# before
docker_env: {}
# after
docker_env:
  image: my-project-image:latest

Defensive patterns

Strategy: validation

Validate before calling

import yaml
def validate_mlproject(path):
    spec = yaml.safe_load(open(path))
    env = spec.get('docker_env') or {}
    if spec.get('docker_env') is not None and not env.get('image'):
        raise ValueError("MLproject docker_env must include an 'image' field")

Prevention

Always include docker_env.image when environment type is docker in MLproject
Validate MLproject YAML in CI with a small schema check
Key the field exactly 'image' (not 'images' or 'name')

When it happens

Trigger: Running `mlflow run --backend docker` (or calling ProjectUtils.get_docker_env / validate_docker_env via _run) on an MLproject whose environment is `docker: {}` or `docker: {image: null}`, or whose docker_env omits the image field entirely.

Common situations: Hand-editing MLproject YAML and forgetting the image key; copying an MLproject that uses 'build' semantics assuming MLflow infers the image; typos like 'images' instead of 'image'.

Related errors

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