1. 概要

mlflow は、機械学習の実験の記録を残す際に非常に有用なツールである。

しかし、 mlflow の version をアップデートしたところ、 mlflow の起動コマンドでエラーが発生するようになった。エラーは、mlflow.exceptions.MlflowException: The filesystem tracking backend (e.g., './mlruns') is in maintenance mode というものだった。

この問題の原因と対策を調査した結果を、この記事に記載する。

2. 依存関係

item	version
mlflow	`2.13.2` から `3.14.0` にアップデートした

mlflow 2.13.2 では問題なく動いていたが、 3.14.0 にアップデート後に mlflow を起動しようとしたところ、タイトルの記載のエラーが発生したわけである。

3. 症状

mlflow 起動時に発生するようになったのは以下のエラーである。

mlflow ui --host 0.0.0.0

...

mlflow.exceptions.MlflowException: The filesystem tracking backend (e.g., './mlruns') is in maintenance mode … set MLFLOW_ALLOW_FILE_STORE=true to opt out of this exception.

エラー全文が気になる方は以下を開いて見てほしい。

エラー全文

# mlflow ui --host 0.0.0.0
/usr/local/lib/python3.11/site-packages/pydantic/_internal/_fields.py:132: UserWarning: Field "model_name" in PromptModelConfig has conflict with protected namespace "model_".

You may be able to resolve this warning by setting `model_config['protected_namespaces'] = ()`.
  warnings.warn(
Backend store URI not provided. Using ./mlruns
Registry store URI not provided. Using backend store URI.
2026/09/29 19:25:44 ERROR mlflow.cli: Error initializing backend store
2026/09/29 19:25:44 ERROR mlflow.cli: The filesystem tracking backend (e.g., './mlruns') is in maintenance mode and will not receive further updates. Please migrate to a database backend (e.g., 'sqlite:///mlflow.db') to access the latest MLflow features. The `mlflow migrate-filestore` tool migrates your existing data losslessly. See https://mlflow.org/docs/latest/self-hosting/migrate-from-file-store for migration guidance. If the filesystem backend is required for your workflow, set `MLFLOW_ALLOW_FILE_STORE=true` to opt out of this exception.
Traceback (most recent call last):
  File "/usr/local/lib/python3.11/site-packages/mlflow/cli/__init__.py", line 684, in server
    initialize_backend_stores(
  File "/usr/local/lib/python3.11/site-packages/mlflow/server/handlers.py", line 744, in initialize_backend_stores
    tracking_store = _get_tracking_store(backend_store_uri, default_artifact_root)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mlflow/server/handlers.py", line 669, in _get_tracking_store
    _tracking_store = _tracking_store_registry.get_store(store_uri, artifact_root)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mlflow/tracking/_tracking_service/registry.py", line 45, in get_store
    return self._get_store_with_resolved_uri(resolved_store_uri, artifact_uri)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mlflow/tracking/_tracking_service/registry.py", line 56, in _get_store_with_resolved_uri
    return builder(store_uri=resolved_store_uri, artifact_uri=artifact_uri)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mlflow/server/handlers.py", line 436, in _get_file_store
    return FileStore(store_uri, artifact_uri)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mlflow/store/tracking/file_store.py", line 225, in __init__
    raise MlflowException(
mlflow.exceptions.MlflowException: The filesystem tracking backend (e.g., './mlruns') is in maintenance mode and will not receive further updates. Please migrate to a database backend (e.g., 'sqlite:///mlflow.db') to access the latest MLflow features. The `mlflow migrate-filestore` tool migrates your existing data losslessly. See https://mlflow.org/docs/latest/self-hosting/migrate-from-file-store for migration guidance. If the filesystem backend is required for your workflow, set `MLFLOW_ALLOW_FILE_STORE=true` to opt out of this exception.

4. 原因

原因は、 mlflow の version アップデートなのだが、アップデートによって一体何が変わったのだろうか。それは、実験記録データの保存形式である。

mlflow v2 系までは mlruns/ ディレクトリ以下に純粋なファイルの形で実験記録を保存するのがデフォルトの方法だった。しかしその仕組みは、 maintenance mode という状態になったらしく、今後保守されない予定とのこと。 v3 では基本的には動作しない。

また、v3 では Database へデータを保存する形式が推奨されているようで、私はそれに則ることにした。この、保存形式の変更に関する対処を行わない限り、今回のエラーは解消しない。

5. 対策

一応、環境変数を export MLFLOW_ALLOW_FILE_STORE=true の様に設定すれば、旧形式 mlruns/ への保存に頼って mlflow を使用し続けることもできるらしい。

しかしながら、この方式がいつ廃止されるかもわからないし、古いやり方にしがみつく生き方はしたくないので、 Database に保存する方式へと移行することにした。

5-1. 新方式への引き継ぎ (migration)

今まで貯めてきた実験記録を、新しい保存形式へと変換する作業について、この「5-1.」で記載する。

今まで mlflow で参照してきた実験結果を新方式へと引き継ぎたい場合は、まず mlruns/ ディレクトリを探しましょう。これまで mlflow に何も特別な設定をしていなかったのであれば、 mlflow 起動コマンドを実行していたディレクトリ内にあると思います。

その、mlruns/ フォルダがあるディレクトリで以下のコマンドを打つと、

mlflow migrate-filestore --source ./mlruns --target sqlite:///mlflow.db

過去の実験記録を新方式のデータ形式へと変換してくれます。
私の場合は sqlite という Database のデータへと変換しました。

選べる Database

sqlite の他にも mysql や postgresql が選べるらしいです💡
設定方法は各自で調査されたい( ˘ω˘)ｽﾔｧ...

私は sqlite で良いので、以下のようにしました。

# migration コマンド
mlflow migrate-filestore --source ./mlruns --target sqlite:///mlflow.db

# 実行結果
/usr/local/lib/python3.11/site-packages/pydantic/_internal/_fields.py:132: UserWarning: Field "model_name" in PromptModelConfig has conflict with protected namespace "model_".

You may be able to resolve this warning by setting `model_config['protected_namespaces'] = ()`.
  warnings.warn(
Source: /working_dir/mlruns
Target: sqlite:////working_dir/mlflow.db

Initializing database schema...
2026/09/29 19:23:09 INFO mlflow.store.db.utils: Creating initial MLflow database tables...
2026/09/29 19:23:09 INFO mlflow.store.db.utils: Updating database tables
[1/29] Migrating experiment 0...
[2/29] Migrating experiment 120525628108639726...
[3/29] Migrating experiment 489739014384910772...

... 省略

[27/29] Migrating experiment 902861166596649477...
[28/29] Migrating experiment 972015927236868926...
[29/29] Migrating experiment 974846342137851473...

Migration completed successfully!

==================================================
Migration summary:
==================================================
  entity                      migrated      in DB
  ------------------------- ---------- ----------
  experiments                       29         29
  experiment_tags                    1          1
  runs                             432        432
  params                          4766       4766
  tags                             432        432
  metrics                        88185      88185
  latest_metrics                  2298       2298
==================================================
  source: /working_dir/mlruns
  target: sqlite:////working_dir/mlflow.db
==================================================

To start a server with the migrated data:
  mlflow server --backend-store-uri sqlite:////<dir>/mlflow.db

migration が終わると上記の様なメッセージが標準出力に現れる！

5-2. mlflow 再起動

mlflow ui と mlflow server という起動方法があるが、これまで使っていた方を使うのが確実ではないかと私は考えている。一方、 mlflow server の方が機能が多いらしいと聞いたので、今回は両方の起動方法を試してみた。

5-2-1. `mlflow ui` で起動する

migration に成功すると、最後に mlflow の起動コマンドが以下の様に表示される。（コマンド内容は人によって異なるかも）

# migration 後に表示されるコマンド
mlflow server --backend-store-uri sqlite:////<dir>/mlflow.db

私は mlflow ui を使っていたので ui を使う。さらに、今まで付与してきたオプション host port を忘れずに付与する。

結果として、以下のコマンドを実行することで、これまで通り Web ブラウザから mlflow の UI 画面にアクセスできることを確認した。

# 私の場合
mlflow ui --backend-store-uri sqlite:///./mlflow.db --host 0.0.0.0 --port 5003

5-2.2. `mlflow server` で起動する

ここからは必要な対処かどうかわかっていないのだが、 mlflow server コマンドで起動する場合に注意すべきことを ChatGPT に相談したところ、「実験記録を保存する側のソースコードも修正した方がいい」という指摘を受けた。

もし、 python コードに mlflow.set_tracking_uri() の様な記述があれば、そこで実験結果などを mlflow に記録する際の通信経路を指定しているわけである。

この mlflow.set_tracking_uri() の記述に関して、私は元々 mlflow.set_tracking_uri("http://0.0.0.0:5003") としていたが、「0.0.0.0 は辞めた方が良い」「localhost なら良い」と ChatGPT から指摘を受けた。

そこで以下のように書き換えておいた。

import mlflow

- mlflow.set_tracking_uri("http://0.0.0.0:5003")
+ mlflow.set_tracking_uri("http://localhost:5003")

このコードのある状態で起動コマンドは以下のようにしている。

mlflow server --backend-store-uri sqlite:///./mlflow.db --host 0.0.0.0 --port 5003

もしかしたら 0.0.0.0 のままでも問題なかったのかもしれないが、この状態であれば特に問題なく mlflow に実験記録を残せることを確認した(๑>◡<๑)