Clashのサブスクリプション更新失敗・解析エラーの原因と対処法

まず、サブスクリプションの取得・設定の解析・コアの読み込みを切り分ける

「更新に失敗しました」と表示されても、ノードが使えないとは限りません。通常、サブスクリプションの更新は、クライアントがURLにリクエストを送り、受信したテキストから設定を解析し、生成した設定をコアで検証・読み込む、という3段階で行われます。どの段階で失敗しても、画面にはエラーが表示されます。まずは更新ボタンを何度も押すのではなく、エラーの全文を記録しましょう。

デスクトップクライアントでは、「サブスクリプション」や「設定」画面から更新し、「ログ」画面で詳細を確認できるのが一般的です。項目名はクライアントのバージョンによって異なります。クライアントとコアの名称・バージョン、失敗した時刻、手動更新か自動更新かを記録してください。ClashとClash Meta（現mihomo）では設定への対応状況が完全には一致しないため、アプリ名だけでは互換性を判断できません。

サブスクリプションURLの期限切れ、認証エラー、サーバー側の制限

管理ページではなく、サブスクリプションURLをコピーしたか確認

サブスクリプションURLには、トークンやクエリパラメーター、専用のパスが含まれていることがあります。アカウント管理画面やログインページ、QRコード画像のURLは、サブスクリプションとして使えません。プロバイダーの管理画面から「Clash」または「mihomo」形式のURLをコピーし直し、先頭や末尾に空白、改行、日本語の引用符が入っていないか確認してください。Webページのソースからコピーした場合は、&がHTMLエスケープされた区切り文字であり、元のURLに含まれる文字列ではないことにも注意が必要です。

• 401：通常は認証に関するエラーです。トークンがリセットされていないか、アカウントの有効期限が切れていないか確認してください。詳しい意味はプロバイダーの案内に従いましょう。
• 403：アクセス方針、接続元IP、User-Agent、アカウント権限などによる制限の可能性があります。「URLの期限切れ」とは限りません。
• 404：APIのパスが変更されていないか、URLが途中で切れていないか、以前のサブスクリプションが無効化されていないか確認してください。
• 429：更新を繰り返さず、レスポンスのRetry-Afterまたはプロバイダーの案内に従って待ちましょう。複数の端末で定期更新していると、制限に達することもあります。
• 502、503、504：サーバー側または中継ゲートウェイの障害が考えられます。発生時刻を記録し、時間をおいて再試行してください。

ブラウザーで開けても、クライアントが同じ内容を受信しているとは限らない

ブラウザーではログインCookieが送信されていたり、Webページ上で認証を済ませてから内容が表示されたりすることがあります。通常、クライアントはこうしたセッションを共有しません。HTTPステータスが200でも、本文がログインページや認証画面、「通信量を使い切りました」という案内の場合があります。ステータスコードだけでなく、実際のレスポンス本文を確認してください。サブスクリプションURLを公開オンラインチェッカーに貼り付けないでください。トークンだけで、アカウントに紐づくノード情報へアクセスできることがあります。

ローカルネットワークによる遮断：DNS・TLS・プロキシ経路を確認

サブスクリプションのダウンロード経路と、ノードへの接続経路は同じとは限りません。クライアントによってはGUIが設定をダウンロードし、別のクライアントでは独立したコンポーネントが処理します。システムプロキシ、TUN、クライアントの「プロキシ経由で更新」設定が結果に影響する場合もあります。ブラウザーでサイトにアクセスできても、それが証明するのはブラウザーの現在の経路が使えることだけです。

1. システム時刻を確認する。日付、タイムゾーン、時計が大きくずれていると、TLS証明書の検証に失敗することがあります。自動時刻合わせを有効にしてから、もう一度試してください。
2. ドメインの名前解決を確認する。Windowsではnslookupの後にサブスクリプションのホスト名を指定します。macOSやLinuxではdigを使えます。入力するのはホスト名だけです。トークンを含むパスは付けないでください。
3. 2種類のネットワークで比較する。同じクライアントと設定のまま、スマートフォンのテザリングに切り替えて試してください。テザリングでは成功し、現在のネットワークでは失敗する場合は、ルーターのDNS、企業ネットワークのゲートウェイ、キャプティブポータル認証、ファイアウォールを優先して確認しましょう。
4. ローカルプロキシの待ち受けを確認する。更新に127.0.0.1:7890を使う場合、コアが起動し、そのポートで実際に待ち受けているか確認してください。7890はよくある例にすぎません。現在の設定にあるmixed-portまたはHTTPプロキシのポートを確認しましょう。
5. 変更する項目は一度に1つだけにする。プロキシを使わずに更新する場合と、利用可能なプロキシ経由で更新する場合をそれぞれ試し、結果を記録してください。DNSの変更、TUNの有効化、ルールの編集を同時に行うと、どの変更が効いたのか判断できません。

connection refusedは、接続先のポートでプロセスが待ち受けていない場合によく発生します。i/o timeoutは接続時または読み込み時に起こることがあります。どちらも、ログに記録された接続先と合わせて判断してください。接続先がローカルのプロキシポートならローカルサービスを、サブスクリプションサーバーなら外部へのネットワーク経路を確認します。

User-Agentの制限とサブスクリプションの出力形式

User-AgentはHTTPリクエストヘッダーです。サブスクリプションサービスはこれを基準にクライアントを判別し、完全なClash設定、ノード一覧のみ、または別の形式を返すことがあります。同じURLでも、ブラウザーとクライアントで受信内容が異なるのは珍しくありません。サービスによってはURLのパラメーターで出力形式を明示する必要があり、リクエストヘッダーを変更するだけでは解決できません。

YAMLだけでなく、リクエスト元も確認する

クライアントに「サブスクリプションのUser-Agent」設定がある場合は、プロバイダーの案内に従って入力し、変更前の値も記録してください。関係のないクライアントを安易に偽装すると、プロバイダーから互換性のない項目が返されることがあります。完全な設定の取得はYAMLの解析前に行われるため、そのYAML内にリクエストヘッダーを追加しても、通常は今回のダウンロードリクエストには影響しません。

mihomoのproxy-providersでは、該当フィールドに対応するバージョンでプロバイダーへのリクエスト設定を指定できます。ただし、これはコアがノードプロバイダーから情報を取得する際の設定であり、GUIクライアントがサブスクリプション全体を更新する入口とは別です。更新に失敗した場合は、ログが設定サブスクリプションとproviderのどちらを指しているか、まず確認してください。

レスポンスがどの種類のデータか確認する

形式の変換が必要な場合は、サブスクリプションプロバイダーが提供するエクスポート方法か、信頼できるローカルツールを優先してください。第三者のオンライン変換サービスには元のURLやノードの認証情報が渡るため、単なるテキストエディターではなく、アカウントにアクセスできるサービスとして扱いましょう。

YAML解析エラー：まず本文を確認し、次に行番号を見る

mapping values are not allowed、did not find expected key、cannot unmarshalなどのエラーが出たら、まずダウンロードしたファイルをローカルのテキストエディターで開いてください。先頭が<!DOCTYPE html>なら、認証やネットワークの問題を確認します。YAMLのインデントを調整しても解決しません。

インデント・データ型・参照先を順番に確認

• インデント：タブではなく半角スペースを使い、同じ階層ではインデントを統一してください。エラーに表示される行番号は、パーサーが処理を続けられなくなった位置を示すだけで、原因はその前の行にある場合もあります。
• コロンと引用符：「コロン＋スペース」を含む名前は引用符で囲みます。例：name: "香港: 01"。YAMLの引用符に全角のかぎ括弧を使わないでください。
• フィールドのデータ型：ポート番号は通常数値、真偽値は通常trueまたはfalseです。proxiesやrulesなどのリストでは、ハイフンを使った構造が正しいか確認してください。
• キーの重複：同じ階層にdns:やrules:を複数記述しないでください。重複キーの扱いはパーサーによって異なるため、1つにまとめてから検証しましょう。
• 名前の参照：ポリシーグループが参照するノードや、ルールが指定するポリシーグループが存在し、名前が一致しているか確認してください。サブスクリプション更新でノード名が変わると、以前の手動設定による参照も無効になります。

以下の設定は、ローカルでの解析・読み込み手順を確認するためのものです。すべての接続は直接接続で、リモートノードは含まれません。既存のサブスクリプションに上書きせず、別のテストファイルとして保存してください。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: "出口選択"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,出口選択

このサンプルが読み込めてサブスクリプションが読み込めない場合、原因はサブスクリプションの内容、マージスクリプト、フィールドの互換性にある可能性が高いと考えられます。ただし、外部のサブスクリプションURLへのアクセスや、プロキシノードの接続確認には使えません。ポート競合が表示された場合は、既存のプロセスを停止するか、空いている別のポートを指定してから読み込んでください。

mihomoのコマンドラインを使う場合は、専用のディレクトリで次の設定チェックを実行できます。ファイル名subscription-test.yamlは、先ほど保存したテストファイルを指します。設定にリモートプロバイダーが含まれていると、チェック中にファイルやネットワークへのアクセスが発生することがあります。YAMLの構文だけを検査するものではありません。

mihomo -t -f subscription-test.yaml

コアの非互換、設定のマージ、更新後の読み込み失敗

YAMLを解析できても、コアで使えるとは限りません。サブスクリプションに含まれるノードのプロトコル、トランスポート設定、ルールの種類が、現在のコアでサポートされていない場合があります。unsupported proxy typeや未知のルールタイプが表示されたら、クライアントの「バージョン情報」またはコア情報画面で実際のバージョンを確認し、該当するコアのドキュメントと照らし合わせてください。アプリとコアのバージョンは別々に管理されています。

元の設定・拡張設定・実行中の設定に分けて切り分ける

1. サブスクリプションからダウンロードした元ファイルを保存し、対応するコアで検証できるか確認してください。
2. その設定に紐づくオーバーライド、マージ、スクリプト機能を一時的に無効にします。設定場所はクライアントの設定編集画面で確認してください。
3. 元ファイルに問題がない場合は、ローカル拡張を1つずつ戻し、proxy-groups、rules、プロバイダー名が上書きされていないか確認します。
4. providerの更新に失敗する場合は、そのproviderのurl、保存先パス、レスポンス構造、更新ログを確認してください。トップレベルの設定だけを再読み込みしても解決しません。

エラーを消すために未知のフィールドをすべて削除しないでください。プロトコルのハンドシェイクや通信方式を決めるフィールドもあり、削除すると読み込みに成功してもノードが接続できなくなることがあります。プロバイダーが明示的に対応している形式を選ぶか、その設定を扱える保守中のクライアントとコアを使いましょう。

更新後の動作確認と問い合わせ時のチェック項目

修正後に手動で1回更新し、更新時刻、ノード数、コアの読み込みログを確認してください。ノード数が正常なのは最初の確認にすぎません。ノードを1つ選び、普段使うサイトにアクセスして、接続ログのポリシーグループと出口が想定どおりか確認しましょう。遅延テストに成功しても、すべての通信が使えるとは限りません。ルールに問題があれば、特定のドメインで誤った出口が選ばれることがあります。

• 取得成功：ログにHTTP、DNS、TLSエラーがなく、Webページではなく想定した形式のデータを受信している。
• 解析成功：YAMLの行番号エラー、フィールドの型エラー、参照先の不足がない。
• 読み込み成功：実行中の設定が更新後の内容に切り替わっており、コアが以前の設定に戻ったり、そのまま使い続けたりしていない。
• 実際の接続に成功：新しく確立した接続を確認し、適用されたルールとポリシーグループを照合する。キャッシュされたページだけで判断しない。

必要な情報を添えて、認証情報は隠して問い合わせる

クライアントの開発者やサブスクリプションプロバイダーに問い合わせる際は、OS、クライアントのバージョン、コアのバージョン、エラー発生時刻、HTTPステータスコード、関連するログを添えてください。プロキシを使わない場合と使う場合、現在のネットワークとテザリングでの結果の違いも説明しましょう。スクリーンショットでは、サブスクリプションURL全体、トークン、ノードのパスワード、アカウント情報を隠してください。ドメインだけを隠してクエリパラメーターを残すと、認証情報が漏れるおそれがあります。

確認の順序は、まずURLと認証、次にレスポンス内容とネットワーク経路、その後に形式・YAML・コアの互換性、最後にローカルのオーバーライドです。一度に変更するのは1項目にして、変更前後の結果を記録してください。クライアントを何度も再インストールするより、サブスクリプション更新のどの段階で失敗したかを特定しやすくなります。