mlflow/mlflow · error · HTTPException

e.message (from submit_job failure)

Error message

e.message (from submit_job failure)

What it means

The REST job API's submit_job endpoint converts MlflowExceptions from job function resolution or submission (e.g. unknown job_name, invalid params, submission failure) into a FastAPI HTTPException carrying the original message and mapped HTTP status.

Source

Thrown at mlflow/server/job_api.py:85

    timeout: float | None = None


@job_api_router.post("/", response_model=Job)
def submit_job(payload: SubmitJobPayload, request: Request) -> Job:
    from mlflow.server.jobs import submit_job
    from mlflow.server.jobs.utils import _load_function, get_job_fn_fullname

    job_name = payload.job_name
    # Record the caller (stamped on request.state by the middleware; flask.g isn't populated
    # there) as the job creator, so ownership checks on get/cancel recognize the submitter.
    creator = getattr(request.state, "username", None)
    try:
        function_fullname = get_job_fn_fullname(job_name)
        function = _load_function(function_fullname)
        job = submit_job(function, payload.params, payload.timeout, creator=creator)
        return Job.from_job_entity(job)
    except MlflowException as e:
        raise HTTPException(
            status_code=e.get_http_status_code(),
            detail=e.message,
        )


@job_api_router.patch("/cancel/{job_id}", response_model=Job)
def cancel_job(job_id: str) -> Job:
    from mlflow.server.jobs import cancel_job

    try:
        job = cancel_job(job_id)
        return Job.from_job_entity(job)
    except MlflowException as e:
        raise HTTPException(
            status_code=e.get_http_status_code(),
            detail=e.message,
        )

View on GitHub (pinned to 6a27f2decc)

Solutions

1. Check the HTTPException detail for the underlying cause and correct job_name/params accordingly.
2. Ensure the job function module is installed/importable on the server process.
3. Catch the HTTPException client-side and surface detail to the user.

Example fix

// before
job = submit_endpoint(job_name="unknown_job", params={})
// after
try:
    job = submit_endpoint(job_name="mlflow.genai...", params={"experiment_id": "1"})
except httpx.HTTPStatusError as e:
    print(e.response.json()["detail"])

# client-side preflight
assert job_name in known_registered_jobs
assert all(k in params for k in required_params[job_name])

try:
    job = submit_via_api(job_name, params)
except httpx.HTTPStatusError as e:
    detail = e.response.json().get("detail")
    ...  # log detail, which is the underlying MlflowException message
    raise

When it happens

Trigger: POST /job/submit (used by evaluation, scorer, and prompt-optimization handlers) where get_job_fn_fullname, _load_function, or submit_job raises MlflowException — e.g. unregistered job_name or invalid params.

Common situations: Submitting a job whose name is not registered on the server; invalid params payload failing job-side validation; plugin/job module failing to import on the server.

Related errors

• e.message (from get_job failure)
• e.message (from cancel_job failure)
• e.detail
• {"error_code": e.error_code, "message": e.message}
• Traces not found: {missing_ids}

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