Fixed: "MlflowException: API request to … failed with exception … Max retries exceeded" Connection Refused in MLflow
An MLflow training run printed seven urllib3 retry warnings over about four minutes, then failed with MlflowException: API request to … failed with exception … Max retries exceeded … [Errno 61] Connection refused. Nothing was listening at the tracking URI. MLflow's client retries for minutes before it gives up, which makes a missing server look like a hang. Starting the server fixed it, and MLFLOW_HTTP_REQUEST_MAX_RETRIES makes the same mistake fail in seconds.
What I Was Doing
I ran the training command of the house-price project from the MLflow series, MLflow 3.18.0 on macOS, with the tracking URI set to http://127.0.0.1:8099. No tracking server was running on that port. env sets an environment variable for one command:
env MLFLOW_TRACKING_URI=http://127.0.0.1:8099 uv run train --n-estimators 10
What I Expected
A finished run in a couple of seconds, with its scores and a link to it in the UI, like every run before it.
What I Got
Nothing for a few seconds, then retry warnings, further and further apart. Each one is a long single line:
2026/11/13 17:42:17 WARNING urllib3.connectionpool: Retrying (Retry(total=6, connect=6, read=7, redirect=7, status=7)) after connection broken by 'NewConnectionError("HTTPConnection(host='127.0.0.1', port=8099): Failed to establish a new connection: [Errno 61] Connection refused")': /api/2.0/mlflow/experiments/get-by-name?experiment_name=house-price-prediction
2026/11/13 17:42:22 WARNING urllib3.connectionpool: Retrying (Retry(total=5, connect=5, read=7, redirect=7, status=7)) after connection broken by 'NewConnectionError("HTTPConnection(host='127.0.0.1', port=8099): Failed to establish a new connection: [Errno 61] Connection refused")': /api/2.0/mlflow/experiments/get-by-name?experiment_name=house-price-prediction
...
2026/11/13 17:46:24 WARNING urllib3.connectionpool: Retrying (Retry(total=0, connect=0, read=7, redirect=7, status=7)) after connection broken by 'NewConnectionError("HTTPConnection(host='127.0.0.1', port=8099): Failed to establish a new connection: [Errno 61] Connection refused")': /api/2.0/mlflow/experiments/get-by-name?experiment_name=house-price-prediction
Then a long traceback, ending in:
mlflow.exceptions.MlflowException: API request to http://127.0.0.1:8099/api/2.0/mlflow/experiments/get-by-name failed with exception HTTPConnectionPool(host='127.0.0.1', port=8099): Max retries exceeded with url: /api/2.0/mlflow/experiments/get-by-name?experiment_name=house-price-prediction (Caused by NewConnectionError("HTTPConnection(host='127.0.0.1', port=8099): Failed to establish a new connection: [Errno 61] Connection refused"))
From the first warning at 17:42:17 to the last at 17:46:24, the run spent about four minutes doing nothing useful.
What I Checked
What the request was. The URL ends in /api/2.0/mlflow/experiments/get-by-name: the first thing the training code does is mlflow.set_experiment(), which looks the experiment up by name on the server. The run never got further.
What the error says. [Errno 61] Connection refused is macOS's way of saying that nothing accepted a connection at that address and port. So the request never reached any server.
Whether a server was running there. It wasn't. My tracking server was on port 8080, where /health answers:
curl -i http://127.0.0.1:8080/health
HTTP/1.1 200 OK
date: Fri, 13 Nov 2026 12:32:04 GMT
server: uvicorn
content-length: 2
content-type: text/plain; charset=utf-8
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
vary: Origin
OK
Why it took four minutes. MLflow retries failed HTTP requests. In MLflow 3.18.0's mlflow/environment_variables.py, MLFLOW_HTTP_REQUEST_MAX_RETRIES "Specifies the maximum number of retries with exponential backoff for MLflow HTTP requests", default 7, and a comment next to it explains the choice: "Assuming 2 seconds per retry, 7 retries with backoff will take ~ 4 minutes, which is appropriate for most rate limiting scenarios". The warnings match: total=6 down to total=0, with waits of about 5, 9, 16, 32, 65 and 120 seconds in between. Exponential backoff means each wait is about twice the last, and urllib3, the HTTP library underneath, never waits more than 120 seconds.
The same run without retries. With MLFLOW_HTTP_REQUEST_MAX_RETRIES=0, the run failed within seconds, with no warnings and the same final line:
env MLFLOW_TRACKING_URI=http://127.0.0.1:8099 MLFLOW_HTTP_REQUEST_MAX_RETRIES=0 uv run train --n-estimators 10
mlflow.exceptions.MlflowException: API request to http://127.0.0.1:8099/api/2.0/mlflow/experiments/get-by-name failed with exception HTTPConnectionPool(host='127.0.0.1', port=8099): Max retries exceeded with url: /api/2.0/mlflow/experiments/get-by-name?experiment_name=house-price-prediction (Caused by NewConnectionError("HTTPConnection(host='127.0.0.1', port=8099): Failed to establish a new connection: [Errno 61] Connection refused"))
Why It Happens
The tracking URI pointed at an address where no MLflow server was listening: the server wasn't started, had stopped, or runs on another port or address. MLflow's client treats a refused connection as possibly temporary, and retries seven times with growing waits before it reports the failure. So the first sign of a missing server is a quiet terminal, and the error comes minutes later.
The Fix
Start the server, or point the URI at the one that's running. In the server's folder:
uv run mlflow server --port 8080
How to Start an MLflow Tracking Server on Your Computer covers it step by step. Then check that your code uses the same address: here, the project's .env file sets MLFLOW_TRACKING_URI=http://127.0.0.1:8080, and nothing in the terminal overrides it. How to Set the MLflow Tracking URI in Python shows which setting wins.
Optional: fail fast while you develop. Lower the retries in the terminal you train from, so a wrong address fails in seconds:
- macOS / Linux
- Windows (PowerShell)
export MLFLOW_HTTP_REQUEST_MAX_RETRIES=0
$env:MLFLOW_HTTP_REQUEST_MAX_RETRIES = "0"
Keep the default for long training jobs: the retries are what carry a run through a server that restarts or briefly refuses requests.
After the Fix
With the server running on port 8080 and no override in the terminal, the same command finished in about a second:
uv run train --n-estimators 10
2026/11/13 17:47:45 INFO house_price_prediction: Loading the California Housing data
2026/11/13 17:47:46 INFO house_price_prediction: Training on 16512 rows
2026/11/13 17:47:46 INFO house_price_prediction: Run unleashed-tern-688: MAE 0.349, RMSE 0.533, R2 0.783
🏃 View run unleashed-tern-688 at: http://127.0.0.1:8080/#/experiments/1/runs/48c46dafc36a488f872de210eb023829
🧪 View experiment at: http://127.0.0.1:8080/#/experiments/1
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
| Waiting for the "hang" to finish | Four minutes pass before the real error | Check the server with curl on its /health path |
| Starting the server in another terminal on a different port | The URI and the server disagree | Use one port everywhere, such as 8080 |
Leaving a test MLFLOW_TRACKING_URI set in the terminal | It overrides your .env for every later run | Close the terminal, or remove the variable |
| Setting retries to 0 for long jobs | A brief server restart fails the whole run | Lower retries only while developing |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Retrying (Retry(total=6, … warnings, then Max retries exceeded | No server at the tracking URI | Start the server or correct the URI |
curl to /health also says Connection refused | The server isn't running on that port | Start it, and read the port in its Uvicorn running on line |
/health answers but runs still fail | The code uses a different address | Print mlflow.get_tracking_uri() before logging |
FAQ
Why didn't it fail right away?
MLflow retries a failed request seven times by default, waiting longer each time, to ride out short outages and rate limits. With a server that isn't there, that adds up to about four minutes.
Does Connection refused mean a firewall blocked it?
Not here. It means no program was listening on that address and port. The server on port 8080 answered at once.
Is [Errno 61] the same on every system?
It's the error number macOS uses for a refused connection. The words Connection refused are what to look for.
Conclusion
MlflowException: API request to … failed with exception … Max retries exceeded … [Errno 61] Connection refused means MLflow couldn't reach a tracking server at its tracking URI, after seven retries that took about four minutes. Starting the server on the address the code uses fixed it, and MLFLOW_HTTP_REQUEST_MAX_RETRIES=0 makes the same mistake show up in seconds while you develop.
Additional Resources
- MLflow environment variables —
MLFLOW_HTTP_REQUEST_MAX_RETRIESand the other HTTP settings. - MLflow Tracking Server — starting the server.
