Could not get string corresponding to run status {status}. V

Error message

Could not get string corresponding to run status {status}. Valid run statuses: {list(RunStatus._STATUS_TO_STRING.keys())}

What it means

RunStatus.to_string converts an integer status enum value back to its string name and raises when the integer is not a known RunStatus value. This guards against corrupt or out-of-range status integers.

Source

Thrown at mlflow/entities/run_status.py:29

    KILLED: int = ProtoRunStatus.Value("KILLED")

    _STRING_TO_STATUS: dict[str, int] = {k: ProtoRunStatus.Value(k) for k in ProtoRunStatus.keys()}
    _STATUS_TO_STRING = {value: key for key, value in _STRING_TO_STATUS.items()}
    _TERMINATED_STATUSES = {FINISHED, FAILED, KILLED}

    @staticmethod
    def from_string(status_str: str) -> int:
        if status_str not in RunStatus._STRING_TO_STATUS:
            raise Exception(
                f"Could not get run status corresponding to string {status_str}. Valid run "
                f"status strings: {list(RunStatus._STRING_TO_STATUS.keys())}"
            )
        return RunStatus._STRING_TO_STATUS[status_str]

    @staticmethod
    def to_string(status: int) -> str:
        if status not in RunStatus._STATUS_TO_STRING:
            raise Exception(
                f"Could not get string corresponding to run status {status}. Valid run "
                f"statuses: {list(RunStatus._STATUS_TO_STRING.keys())}"
            )
        return RunStatus._STATUS_TO_STRING[status]

    @staticmethod
    def is_terminated(status: int) -> bool:
        return status in RunStatus._TERMINATED_STATUSES

    @staticmethod
    def all_status() -> list[int]:
        return list(RunStatus._STATUS_TO_STRING.keys())

View on GitHub (pinned to 6a27f2decc)

Solutions

Only pass RunStatus enum members: RunStatus.to_string(RunStatus.FINISHED).
Check membership first: if status in RunStatus._STATUS_TO_STRING.
Map foreign codes to RunStatus values before conversion.

Example fix

// before
name = RunStatus.to_string(status_int)  # raises for unknown ints
// after
name = RunStatus.to_string(status_int) if status_int in RunStatus._STATUS_TO_STRING else 'UNKNOWN'

Defensive patterns

Strategy: validation

Validate before calling

from mlflow.entities import RunStatus
if status not in RunStatus._STATUS_TO_STRING:
    status = RunStatus.FAILED  # or translate foreign numeric codes first

Type guard

from mlflow.entities import RunStatus
def is_run_status(v) -> bool:
    return isinstance(v, int) and v in RunStatus._STATUS_TO_STRING

Try / catch

try:
    name = RunStatus.to_string(status)
except Exception:
    name = 'UNKNOWN'  # or translate the foreign code, then retry

Prevention

Only pass RunStatus enum members, never raw ints from other systems.
Translate foreign numeric status codes before conversion.
Guard with `status in RunStatus._STATUS_TO_STRING` for untrusted input.

When it happens

Trigger: Calling RunStatus.to_string with an int not in the enum (e.g. 0, 99), often an uninitialized value or a status from a foreign system.

Common situations: Reading status ints from external databases/APIs that use different numeric codes; arithmetic on status values; passing None or a string where an int is expected.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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