サブスクリプションのダウンロード失敗と設定の読み込み失敗を切り分ける
「サブスクリプションを読み込めない」といっても、発生箇所はさまざまです。クライアントが応答を受け取れない、サーバーからエラーページが返る、設定ファイルを解析できない、設定内のプロトコルに現在のコアが対応していない、といったケースがあります。コアとの互換性を重点的に確認する必要があるのは最後のケースだけです。ノードを何度も切り替えても、最初の3つの問題は通常解決しません。
FlClash は mihomo コアを使用します。クライアントはサブスクリプションの管理、画面表示、設定の処理を担当し、コアは設定の検証とトラフィックの転送を担当します。画面に「更新失敗」と表示されたら、更新時のエラー詳細に加え、その後にコアの読み込みエラーが出ていないかも確認してください。メニュー名はバージョンによって異なる場合があります。以下では機能名を手がかりに説明し、特定バージョンの画面操作をすべてのプラットフォーム共通の手順として扱いません。
| エラーの手がかり | まず確認する項目 | 次の手順 |
|---|---|---|
timeout、no such host | リンクへの接続とドメイン名の解決 | ダウンロード要求を試し、使用されるネットワーク経路を確認する |
HTTP 401、403、404 | 認証、アクセス制限、URLの変更 | サービス提供元のアカウントページで契約状況と最新URLを確認する |
yaml:、unmarshal | レスポンス内容と YAML のデータ型 | まずHTMLではないことを確認し、該当行とその前後を調べる |
unsupported proxy type | プロキシプロトコルとコアの対応状況 | 実際に動作しているコアのバージョンとノードのフィールドを確認する |
proxy … not found | プロキシグループとノードの参照 | 名前、フィルター条件、上書き適用後の最終設定を確認する |
調査前に控えておく3つの情報
- FlClash のバージョン、OS、実際に動作しているコアのバージョンを記録します。コアとクライアントの更新時期は一致するとは限らないため、「最新版」とだけ書かないでください。
- 失敗した時刻の前後のログを保存します。たとえば更新操作の前後30秒を記録し、ダウンロード、解析、読み込みのどの段階で失敗したかを切り分けます。
- 引き続き使える設定はバックアップしてください。読み込みテストには新しいテスト用設定を使い、唯一使える設定ファイルをすぐに上書きしないようにします。
サブスクリプションURLには、アクセス用トークンが含まれていることがよくあります。スクリーンショット、ログ、設定を共有する前に、URLのクエリパラメーターに含まれる認証情報を削除し、ノードのパスワード、UUID、認証ヘッダー、個人用パスも伏せてください。ドメイン名を隠すだけでは、サブスクリプションへのアクセス権を保護できません。
第1段階：リンクへの接続と HTTP ステータスを確認する
まずURLを確認し、その後ネットワークを調べる
サービス提供元のアカウントページから、Clash または mihomo 用のサブスクリプションURLをコピーし直します。先頭が https:// か、末尾に空白、改行、引用符、日本語の句読点が紛れ込んでいないか確認してください。アカウントのログインページ、プラン詳細ページ、QRコード画像のURLは、設定用のサブスクリプションURLではありません。QRコードは画像ファイルをクライアントに読み込ませるのではなく、実際のURLにデコードしてから使います。
ブラウザーでURLを開けても、そのときブラウザーからのリクエストが成功したことしか分かりません。ブラウザーはログインCookieを送信している場合があり、クライアントとは異なるプロキシ経路を使っていることもあります。サブスクリプションのバックグラウンド更新では、ブラウザーのログイン状態は通常引き継がれません。そのため、クライアントでの更新と単独のダウンロードを別々にテストし、同じネットワーク経路だと決めつけないでください。
制限付きダウンロードでレスポンスを確認する
macOS または Linux の Bash ターミナルでは、以下のコマンドを使えます。URLは非表示入力で読み込むため、コマンド履歴に直接残りません。サブスクリプションの本文はターミナルに表示せず、カレントディレクトリに保存します。個人がアクセスできる一時作業用ディレクトリで実行してください。
read -r -s -p 'サブスクリプションURLを入力：' SUB_URL
printf '\n'
curl --location --max-redirs 3 \
--proto '=https' --proto-redir '=https' \
--connect-timeout 10 --max-time 30 \
--output subscription-response.txt \
--write-out 'HTTP %{http_code}\n種類 %{content_type}\nバイト数 %{size_download}\n' \
"$SUB_URL"
unset SUB_URL接続タイムアウトは10秒、全体の制限時間は30秒、リダイレクトは最大3回で、HTTPSに限定しています。これらは今回の診断用パラメーターであり、FlClash のデフォルト設定ではありません。Windows PowerShell では同名のパラメーターを使う curl.exe を実行できます。Bash の read や行継続の書き方をそのまま使わないでください。
- HTTP 200：正常なステータス応答を受け取ったことを示しますが、本文の確認は必要です。ログインページやエラーメッセージのページも200を返す場合があります。
- HTTP 301/302：リダイレクト先が想定しているサービスのURLか確認してください。トークンを含む完全なリダイレクトURLを公開しないでください。
- HTTP 401/403：トークンがリセットされていないか、契約が有効か、アカウントにアクセス制限がないか確認してください。403はセキュリティ対策サービスによる場合もあります。
- HTTP 404/410：まずURLの有効期限切れやAPIの移行を確認してください。適当なパスに書き換えて復旧を試みないでください。
- HTTP 429：連続で更新するのをやめ、サーバーの案内に従って待ってください。自動で再試行すると、アクセス制限の時間が延びる場合があります。
- HTTP 5xx：時刻とステータスコードを記録し、しばらくしてから再試行してサービス提供元に報告してください。ローカルの YAML を変更しても、サーバー側の障害は解決できません。
結果が HTTP 000 の場合、報告可能なHTTPステータスを取得できなかったという意味であり、サーバーが実際に「000」を返したわけではありません。curl のエラー内容を確認し、DNS、接続タイムアウト、TLS証明書の問題を調べてください。証明書エラーが出たら、端末の時刻、証明書の有効期限、ネットワークによる干渉を確認します。証明書検証を無効にして恒常的に回避するのは避けてください。
サブスクリプション更新の依存ループを避ける
サブスクリプションのドメインへの接続にプロキシが必要で、使える設定がまだない場合、初回の更新に失敗することがあります。反対に、プロキシの出口がサブスクリプションサービスに拒否される場合は、直接接続のほうが適切かもしれません。サブスクリプション更新時のプロキシ設定やダウンロード方法がクライアントにあるか確認し、一度に変更する経路は1つだけにして結果を記録してください。TUNモードは解析エラーを直す設定ではありません。TUN、DNS、サブスクリプションURLを同時に切り替えないでください。
第2段階：レスポンスがWebページや別形式ではなく、設定ファイルか確認する
ローカルのテキストエディターで subscription-response.txt を開き、自分の端末上だけで確認してください。Content-Type は手がかりになりますが、サーバーが一律に text/plain やダウンロード用の形式を返す場合もあります。レスポンスヘッダーだけで内容が有効かどうかを判断しないでください。
| 本文の特徴 | 考えられる内容 | 対処方法 |
|---|---|---|
<!DOCTYPE html>、<html> | ログインページ、セキュリティ確認、エラーページ | サブスクリプションURLを取得し直し、認証確認についてサービス提供元に問い合わせる |
{"error": などのJSONデータ | APIエラー、または設定取得用ではないAPI | エラー項目を確認し、認証とアカウントの状態を調べる |
ss://、vmess:// などの1行ずつのURI | ノードリンクの一覧 | クライアントがこのインポート形式に対応しているか確認し、可能なら Clash/mihomo 形式を選ぶ |
| 連続したBase64文字列 | エンコードされたノード一覧の可能性 | サブスクリプション形式を確認し、YAMLとしてそのまま読み込まない |
proxies:、proxy-groups: | Clash設定の可能性 | インデント、フィールドの型、参照関係を続けて確認する |
完全な設定ファイルとプロバイダー用のノードファイルも別物です。proxies: だけのファイルは proxy-providers で使うものかもしれませんが、クライアントに必要なプロキシグループやルールを含まない場合があります。payload: だけのファイルは通常ルールセットであり、ノードのサブスクリプションではありません。読み込み時の動作はクライアントがテンプレートを補完するかどうかによって異なります。「YAMLとして読み込める」ことと「完全な設定として動作する」ことは同じではありません。
リクエストの User-Agent に応じて異なる形式を返すサービスもあります。同じURLでもブラウザーとクライアントで内容が異なる場合は、正しい接続先と出力形式をサービス提供元に確認してください。リクエストヘッダーを安易に偽装するのは避けましょう。形式変換が必要なら、サービス提供元の変換機能か、自分で管理できる変換ツールを優先してください。サブスクリプション全体を公開の変換サイトに渡すと、記載された認証情報も渡すことになります。
第3段階：YAML構文、フィールドの型、名前の参照を確認する
エラー行は異常が検出された位置であり、原因の位置とは限らない
yaml: line 12 は、12行目付近で解析エラーが検出されたことを示します。実際の原因は、引用符が閉じていない、親階層のインデントが変わっているなど、前の行にあるかもしれません。エラー行の前後5行を確認し、ノード一覧をまとめて削除しないでください。
- インデントにはスペースを使い、Tabは使わないでください。同じ階層ではインデントをそろえます。たとえば、階層ごとにスペース2つにします。
- マッピングのフィールドには半角コロンを使い、通常はコロンの後ろにスペースを入れます。例：
mode: rule。 - リスト項目には半角の
-を使い、対応するフィールドの下に配置されているか確認してください。 :、#、複雑な記号を含む名前、パスワード、URLは、適切な引用符で囲んでください。引用符の内側も、それぞれのエスケープ規則に従う必要があります。- ポートの値は整数、
proxiesはリストである必要があります。構文が正しくても、型が違えば設定のデコードに失敗します。
最小構成で構文エラーを切り分ける
以下は問題の切り分け用に作成した、プロキシノードを含まない最小の直接接続設定です。混合ポートには 17890 を指定していますが、これは例の値です。使用前に、ほかのプロセスが同じポートを使っていないことを確認してください。この設定にはプロキシ経由の通信機能はありません。
mixed-port: 17890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups:
- name: "診断用出口"
type: select
proxies:
- DIRECT
rules:
- MATCH,診断用出口最小構成が検証でき、元のサブスクリプションでは失敗する場合、調査対象は元ファイルと設定のマージ処理です。ポートの競合や権限エラーが続く場合は、実行環境の問題に移っているため、YAML構文エラーとして扱い続けないでください。また、この設定で直接接続できても、プロキシノードが使えることの証明にはなりません。
ローカルに mihomo の実行ファイルがある場合は、ターミナルで mihomo -t -f ./subscription-response.txt を実行して設定を確認できます。このコマンドが使うのは、現在のターミナルから見つかるコアであり、FlClash に同梱されたバージョンとは限りません。プロバイダー設定の検証には外部リソースへのアクセスが必要な場合もあります。管理下にあるローカル環境でテストし、検証に通ってもすべてのノードが接続できるとは限らない点に注意してください。
プロキシグループ、ルール、上書き適用後の最終設定を確認する
プロキシ名が見つからないというエラーが出た場合は、ノード名とプロキシグループからの参照を、空白や大文字・小文字も含めて一字ずつ比較してください。ルールの末尾にある出口名は、存在するノード、プロキシグループ、または組み込みの出力先を指定する必要があります。use で参照する名前は proxy-providers 内のキーに対応している必要があり、プロバイダー名を通常のノード参照の代わりに使うことはできません。
サブスクリプションの元データは検証できるのにクライアントで読み込みに失敗する場合、クライアント側の上書き、設定のマージ、ノードのフィルター条件を確認してください。フィルター式によって候補ノードがすべて除外されたり、名前の変更後に古い参照が残ったりすることがあります。まずテスト用設定でカスタム処理を無効にし、その後1つずつ戻して確認してください。サブスクリプションのキャッシュを直接変更しても、次回更新時に上書きされることがほとんどです。
第4段階：ノードのプロトコルと実際に動作しているコアを確認する
Clash形式の設定だからといって、すべてのClash系クライアントが同じプロトコルに対応しているわけではありません。従来のClash、mihomo、各世代のコアでは、対応するプロトコルやフィールドが異なる場合があります。unsupported proxy type が出たら、まずエラーに表示された type の値を記録し、コアのバージョンとリリースノートを確認してください。
- プロトコル名を確認する。たとえばノードに
type: hysteria2とある場合、そのプロトコルに対応したコアが必要です。種類をssに書き換えても動作するようにはなりません。 - 必須項目とデータ型を確認する。
server、port、パスワードやUUIDなどのフィールドを確認してください。必要な項目はプロトコルによって異なります。 - トランスポートとTLSのパラメーターを確認する。接続先、SNI、WebSocketのパスなどの設定はサーバー側と一致させる必要があります。設定を解析できても、ハンドシェイクのパラメーターが正しいとは限りません。
- フィールドが認識されているか確認する。一部の未知のフィールドは、エラーにならず無視される場合があります。「読み込み成功」だけでは、すべてのオプションが反映されたとは判断できません。
- 互換性のあるサブスクリプション形式を使う。サービス提供元が mihomo 向けの形式を用意している場合は、そちらを選んでください。アップグレードが必要なら、まず設定をバックアップしてからクライアントまたはコアを変更します。
読み込み後に dial timeout、認証エラー、TLSハンドシェイクエラーが出る場合は、問題がノードの接続段階に移っています。YAMLのインデントを修正し続けるのではなく、ノードへの接続性、認証情報、サーバー設定を確認してください。解析成功、コアの起動、ノードへの接続、サービスへのアクセスは、それぞれ別の確認項目です。
修正後の確認手順と問い合わせ時に伝える情報
一度に1つの段階だけを確認する
- サブスクリプションを手動で1回更新し、レスポンスが空でなく、HTTPエラーやダウンロードエラーが出ないことを確認します。
- テスト用設定を読み込み、ログにYAML、プロトコルの種類、名前の参照に関するエラーがないことを確認します。
- コアが安定して動作し、ポートの競合、権限不足、プロバイダーリソースの読み込み失敗がないことを確認します。
- 存在を確認済みのノードを1つ選んで接続をテストし、実際のアプリでルールが選択する出力先も確認します。
- 必要な上書き設定とフィルターを戻し、1つずつ動作を確認します。最後に定期更新を再開してください。
サービス提供元やプロジェクトに問い合わせる際は、OS、クライアントのバージョン、コアのバージョン、失敗時刻、HTTPステータスコード、機密情報を伏せた最初の重要なエラーを伝えてください。YAMLの問題なら、エラー行付近の最小限の断片を添えます。ダウンロードの問題なら、直接接続と現在のプロキシ経由でそれぞれどうなるかを説明してください。認証情報を含むサブスクリプション全体は送らないでください。
サブスクリプションURLを公開スクリーンショット、問い合わせフォーム、変換サービスに掲載してしまった場合は、サービス提供元のアカウントでサブスクリプショントークンをリセットし、各端末の設定を更新してください。ローカルの記録を消しても、すでに漏えいしたアクセス権は無効になりません。
「リンクへの接続 → レスポンス形式 → YAMLと参照 → コアの互換性」の順に確認します。この順序なら、サーバーがログインページを返しているのにポートを何度も変更したり、ノードの接続タイムアウトをサブスクリプション形式のエラーと誤認したりするのを防げます。各フィールドの意味は設定フィールドリファレンス、システムプロキシとTUNを初めて有効にする手順は入門ガイドをご覧ください。