Difyが「キューイング中」から進まない原因と対処法

Difyをセルフホスト環境（Docker Compose）で運用している際、ナレッジベースにファイルをアップロードしてもステータスが「キューイング中（Queuing）」のまま動かなくなるトラブルは、多くのユーザーが直面する壁です。この状態はシステムがタスクを認識していても、何らかの理由で処理を実行する準備が整っていない、あるいは実行部隊が停止していることを示唆しています。

特にDifyは開発の更新速度が非常に速く、2026年7月時点では最新バージョンが1.15.0系に達しており、ほぼ毎週のようにアップデートが繰り返されています。そのため、特定のバージョンに限定された不具合というよりも、環境構築時やアップデート時の設定不備、あるいはミドルウェアの挙動によって本現象が発生するケースが目立ちます。

本記事では、Difyのセルフホスト版においてキューイングが止まる主要な原因と、自力で復旧させるためのステップを解説します。

キューイングが止まる原因

ナレッジ登録が止まる背景には、いくつかの典型的な原因が存在します。まずはご自身の環境で何が起きているのか、以下の3パターンから可能性を絞り込みましょう。

Workerの未起動・設定不備

Difyの非同期処理（重い処理をバックグラウンドで実行する仕組み）を担う「Celery Worker」コンテナが停止している場合や、必要なキュー（タスクの待ち行列）を購読していない設定不備が最も多い原因です。

Difyでは複数のキューが使い分けられており、特にナレッジ登録に関連する「priority_pipeline」などのキューをWorkerが監視できていないと、アップロードされたファイルは処理待ちの列から一歩も進むことができません。これはDocker Compose環境の初期設定や、.envファイルの記述ミス、バージョンアップ時の設定追従漏れなどで頻発します。

APIのレート制限（429）

Embedding（埋め込み）に使用しているAIモデル（OpenAIのtext-embedding-3-smallなど）のAPI側で、短時間の過度なリクエストにより「429 Too Many Requests（レート制限）」や「RateLimitError」が発生しているケースです。

この場合、Difyのシステム自体は正常にタスクを処理しようとしていますが、外部のAPIプロバイダーからアクセスを拒否され続けているため、リトライを繰り返すか、タイムアウトを待つ状態になり、結果としてステータスが「キューイング中」に固定されます。特に無料枠のAPIキーや、低ティアのプランを利用している場合に発生しやすくなります。

大量アップロードによるUI停止

一度に50ファイルを超えるような大量のデータを一括で投入した場合、サーバー側の処理能力以前に、ブラウザ側のUI（ユーザーインターフェース）がフリーズし、ステータスの更新が視覚的に止まって見えることがあります。

この場合、実際にはバックグラウンドで処理が進んでいる可能性もありますが、フロントエンドとの通信が正常に行われないため、ユーザーからは「ずっとキューイング中のまま変わらない」ように見えてしまいます。

Workerとキューの対処法

まずは最も可能性が高い、Celery Workerの状態を確認しましょう。以下の手順でDocker環境をチェックします。

Workerの稼働状況確認

まず、ターミナルでDifyのインストールディレクトリ（dockerディレクトリがある場所）に移動し、以下のコマンドを実行してWorkerコンテナが「Up（起動中）」になっているか確認してください。

docker compose ps

もしWorkerコンテナが起動していない（ExitやPausedになっている）場合は、以下のコマンドで手動起動を試みます。

docker compose -f docker/docker-compose.yaml up -d worker

CELERY_QUEUESの再設定

Workerが起動していてもキューを購読できていない場合は、環境変数の設定を見直します。docker-compose.yamlを確認し、CELERY_QUEUESの環境変数に、ナレッジ処理に必要な「priority_pipeline」が含まれているか確認してください。

設定値の例：
CELERY_QUEUES: "dataset,generation,mail,ops_trace,priority_pipeline"

設定を修正、あるいは確認した後は、以下のコマンドでWorkerを再起動し、変更を確実に反映させます。

docker compose restart worker

その他の確認事項

上記の設定確認を行っても改善しない場合、インフラレベルの深層的な問題や、外部リソースの制限を疑う必要があります。

Redis・DBの起動確認

タスク管理の要となるRedisや、ナレッジを格納するベクトルデータベース（WeaviateやQdrant、Milvusなど）が不安定な場合、タスクが登録されません。

特にRedisに関しては、一時的な停止や接続不備により「Redisにキューキーが作成されない（タスク自体が積み上がらない）」という具体的な症状（GitHub Issue #28513）が報告されています。docker compose psですべてのコンテナが正しく起動しているか確認するとともに、Redisコンテナのメモリ不足やディスク容量の圧迫がないかもチェックしてください。

ログのレート制限確認

Workerのログを詳細に確認することで、外部APIとの通信状況を把握できます。

docker compose logs worker

ログ内に「RateLimitError」や「429」という文字列が表示されている場合は、Embedding API側のクォータ（利用制限）に達しています。この場合はDifyの設定ではなく、APIプロバイダー側での支払設定の確認や、利用制限の緩和申請が必要になります。

また、GitHubの議論（Issue #27473）などでは、根本原因が特定されずにクローズされるケースや、特定の環境条件下で原因不明のまま解消されない事例も報告されています。ログを確認しても致命的なエラーが見当たらないにもかかわらず動作しない場合は、後述する代替手段を検討するか、環境の再構築（クリーンインストール）が必要になる可能性もあります。

代替手段とCloud版の検討

運用の工夫や、インフラ管理の手間を排除することで状況を打破する方法です。

ファイル数の分割

一度に大量のファイルを処理させず、分割してアップロードすることで、システム負荷を抑え、キュー詰まりを物理的に回避できる場合があります。Difyの処理性能はサーバーのスペック（CPU/メモリ）に依存するため、目安として一度にアップロードするファイルを50件未満に抑え、処理の完了を確認しながら進めるのが安全です。

Dify Cloudへの移行

セルフホスト版でのインフラ管理（Dockerの運用、RedisやWorkerのチューニング）や、突発的なキュー詰まりのトラブルシューティングが業務の負担になる場合は、公式が提供するDify Cloud版（SaaS版）への移行が有効な選択肢です。

なお、Cloud版でキューイング詰まりが発生した場合、ユーザー側で設定変更やコンテナの再起動を行う手段は一切提供されていません。対処法としての技術的な情報ソースも存在しないため、Cloud版を利用する場合は「ユーザー側での設定変更による対処は不可能であり、サービス側の復旧を待つか代替案を検討するのみ」というスタンスになります。管理コストを最小化したい場合には適していますが、トラブル時のコントロール権は制限される点に注意してください。

インデックス失敗との違い

今回の「キューイング中のまま止まる」症状は、処理の「入り口」で止まっている状態です。これに対し、ナレッジ登録処理自体は始まるものの、途中で停止したりエラーコードを吐いたりするケースは、パース（解析）やインデックス（ベクトル化）の問題となります。

関連記事：Difyのインデックスに失敗する原因と対処法

処理が「進行」しているのか、それとも最初から「キュー（待ち行列）」から動いていないのかをログやUIで明確に切り分けることが解決の鍵となります。

まとめ

Difyのキューイング詰まりを解消するための要点を整理します。

• 最多原因はWorkerの停止・設定不備：まずはdocker compose psで稼働を確認し、必要に応じてコンテナを再起動する。
• 設定の再確認：CELERY_QUEUES環境変数にpriority_pipelineが含まれているかをチェックし、設定を最新の状態に合わせる。
• ミドルウェアの挙動に注意：Redisの不具合（Issue #28513）によりキューキーが作成されないケースもあるため、各コンテナの健全性を確認する。
• API制限の確認：docker compose logs workerでレート制限（429エラー）が出ていないか確認する。
• 運用の見直し：大量アップロードを避ける。または、インフラ管理を切り離すためにDify Cloud版への移行を検討する（ただしCloud版はユーザー側での設定対処は不可）。

Difyは毎週のようにアップデートされる非常に変化の速いツールです。本記事の手順で解決しない場合は、公式のGitHubリポジトリで自身のバージョンに関連する新しいIssueが報告されていないか、定期的に確認することをおすすめします。