What causes "run_id cannot be empty" in mlflow/mlflow?

Pass a valid run_id string obtained from mlflow.active_run().info.run_id or the MLflow UI.

mlflow/mlflow · error · MlflowException

INVALID_PARAMETER_VALUE

INVALID_PARAMETER_VALUE

Error message

run_id cannot be empty

What it means

Raised by MlflowClient.link_traces_to_run when the run_id argument is empty/None. Linking traces to a run requires a valid run ID, and the client rejects an empty one before sending a request to the tracking store.

Source

Thrown at mlflow/tracking/_tracking_service/client.py:1109

        """
        return self.store.remove_dataset_from_experiments(dataset_id, experiment_ids)

    def link_traces_to_run(self, trace_ids: list[str], run_id: str) -> None:
        """
        Link multiple traces to a run by creating entity associations.

        Args:
            trace_ids: List of trace IDs to link to the run. Maximum 100 traces allowed.
            run_id: ID of the run to link traces to.

        Raises:
            MlflowException: If more than 100 traces are provided or run_id is empty.
        """
        if not trace_ids:
            return

        if not run_id:
            raise MlflowException.invalid_parameter_value("run_id cannot be empty")

        if len(trace_ids) > 100:
            raise MlflowException.invalid_parameter_value(
                f"Cannot link more than 100 traces to a run in a single request. "
                f"Provided {len(trace_ids)} traces."
            )

        return self.store.link_traces_to_run(trace_ids, run_id)

    def unlink_traces_from_run(self, trace_ids: list[str], run_id: str) -> None:
        """
        Unlink multiple traces from a run by removing entity associations.

        Args:
            trace_ids: List of trace IDs to unlink from the run.
            run_id: ID of the run to unlink traces from.

        Raises:

View on GitHub (pinned to 6a27f2decc)

Solutions

Pass a valid run_id string obtained from mlflow.active_run().info.run_id or the MLflow UI.
Start a run first (with mlflow.start_run()) if you expect the run to exist.
Guard the call: return early or raise a clear error if not run_id.

Example fix

// before
client.link_traces_to_run(trace_ids, run_id)  # run_id is None

// after
run = mlflow.active_run()
if run:
    client.link_traces_to_run(trace_ids, run.info.run_id)

Defensive patterns

Strategy: validation

Validate before calling

if not run_id:
    raise ValueError("link_traces_to_run requires a non-empty run_id")
client.link_traces_to_run(trace_ids, run_id)

Type guard

def has_run_id(run_id) -> bool:
    return isinstance(run_id, str) and run_id.strip() != ""

Try / catch

try:
    client.link_traces_to_run(trace_ids, run_id)
except MlflowException as e:
    if e.error_code == "INVALID_PARAMETER_VALUE" and "run_id cannot be empty" in str(e):
        logger.error("No run_id available; ensure mlflow.start_run() or set run_id explicitly")
    else:
        raise

Prevention

Resolve run_id from mlflow.active_run().info.run_id inside a start_run context.
Validate run_id is a non-empty string before any tracking-store call.
Never rely on unset MLFLOW_RUN_ID env vars without a fallback check.

When it happens

Trigger: Calling client.link_traces_to_run(trace_ids, run_id) with run_id='' or None, typically because a variable was never populated, mlflow.active_run() returned None, or the run ID was read from an unset environment variable (e.g. MLFLOW_RUN_ID).

Common situations: Notebook scripts run outside mlflow.start_run() so there is no active run; CI pipelines missing run-id environment variables; deserialized configs where the run_id key is empty.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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