メインコンテンツまでスキップ

Resource Pack Manager トラブルシューティング

このページでは、ResourcePackManagerのコードベースで現在確認できる挙動のみを扱います。

RSPMで何か問題があるとき、最も有用な最初のステップは次のコマンドです：

/rspm status

これは、バージョン、デプロイモード（standalone vs network-backend）、秘密を含まない短いネットワークキーのフィンガープリントとそのキーの出どころ、JavaおよびBedrockパックの状態、アクティブな配信経路とURL、解決された外部ホストと自動検出された公開IP、関連するすべての設定フラグ、プロキシのデプロイに関するリマインダー（ネットワークプロキシ用jarは同じ ResourcePackManager.jar であること）、Floodgate／Geyser-Spigotの検出状況を表示します。プロキシ上でjarが動作しているときにも同じコマンドが存在し、プロキシ側の対応情報（バックエンド一覧、バックエンドごとの取得結果、マージされたパックの状態）を表示します。

コンソールが静かなのは意図的です​

RSPMは配信経路を新たに初期化するたびに、1行だけを出力します — その結果です：

[ResourcePackManager] Resource pack is live via self-hosting — http://play.example.com:25566/rspm.zip
[ResourcePackManager] Resource pack is live via automatic hosting — https://magmaguy.com/rsp/<uuid>

それ以外 — ステージングされた各パック、マージされた各クラスター、各安定性チェック、各セルフホストプローブとその結果 — は既定で抑制されます。RSPMが自力で回復した状況は、警告として報告されません。 セルフホストのプローブが失敗してRSPMが黙ってリモートホスティングに切り替えたなら、それは障害ではなく成功であり、コンソールはそれについて何も言いません。

結果の行は、RSPMが配信URLを選択して公開したことを示します。特定のクライアントがパックをダウンロード・表示できた証拠ではありません。プレイヤーを参加させ、既知のカスタムアイテムやモデルを確認してください。ホスティングやマージの問題を報告する前に、詳細ログを有効にしてください：

/rspm verbose on

そして /rspm reload を実行します。このコマンドは plugins/ResourcePackManager/config.yml に verboseLogging: true を書き込み、設定は再起動をまたいで保持されるので、終わったら /rspm verbose off を実行してください。キーを手で編集しても同じことです。Bedrockコンバーターには別途 bedrockConverterDebug というスイッチがあり、こちらは設定ファイル専用です。

正当に目にする可能性がある警告は本物の障害です：特定のプレイヤーへのパック配信が繰り返し失敗する、クライアントが INVALID_URL を報告する、HTTPポートがバインドできなかった、両方の配信経路が失敗した、あるいはプロキシが数サイクルポーリングしてもどのバックエンドもコンテンツを生成していない、といったケースです。

プレイヤーがリソースパックを受け取れない​

まず以下を確認してください：

  • 通常の自動配信を使いたいなら autoHost を有効にしておく必要があります（selfHostForce はテスト用の明示的な上書きです）
  • マージされたパックが存在し、少なくとも1つの配信経路（セルフホストまたはリモート）が成功している必要があります
  • プレイヤーは参加時にパックを受け取ります。パックが公開されていない間に参加したプレイヤーは、ホスティングの準備ができたときにパックを受け取ります。これには、セッションの途中でホスティングが再登録された場合（期限切れのリモートセッションの後など）も含まれます
  • FloodgateのプレイヤーはJava配信から意図的に除外されます。彼らのBedrockパックセッションはGeyserが所有しているためです

必要であれば：

  1. /rspm status を実行して「Hosting」セクションを確認します。Active delivery には、現在セルフホスト、リモート、いずれが使用中かが表示されます。
  2. 「active delivery: not yet ready」と表示される場合 — ミックスまたはアップロードがまだ進行中です。早く参加しすぎたプレイヤーがいる場合、プラグインはコンソールに大きく警告を出し、配信が準備できた瞬間にパックを自動送信します。
  3. 「active delivery: none — hosting disabled or failed」と表示される場合 — autoHost がオフか、セルフホストのプローブとリモートアップロードの両方が失敗しています。下記の「セルフホストの健全性チェックが失敗した」と「自動ホストがリモートサーバーに到達できない」を参照してください。
  4. verboseLogging: true を設定してから /rspm reload を実行し、コンソールでアップロード／セルフホストのプローブ結果を監視し、テスト用プレイヤーで再参加します。（このフラグがない場合、プローブの各ステップは出力されません — 最終的な「Resource pack is live via ...」の結果行だけが出力されます。）

参加時のパック提示は約1秒遅延します。Javaクライアントが FAILED_DOWNLOAD や DISCARDED を報告した場合、RSPMはそのプレイヤーセッションについて最大3回まで自動的に再試行します。プレイヤーによる拒否、INVALID_URL、FAILED_RELOAD については再試行しません。再試行の枯渇や無効なURLは本物の障害としてログに記録されます。

FAILED_RELOAD は、クライアントがパックをダウンロードしたものの、クライアント自身のリソースのリロードに失敗したことを意味します。同じパックを再びダウンロードしても解決しません。RSPMは Client <name> reported FAILED_RELOAD for the resource pack. Check that client's latest.log for the resource reload error; not retrying. とログに記録します。そのプレイヤーのクライアントの latest.log を読み、クライアントが拒否したアセットやパックのメタデータを特定してください。

別の仕組みがホスティングと配信を担当する場合（autoHost: false）、RSPMはURLを送信しません。RSPMの前にHTTPSリバースプロキシを置く場合は、autoHost: trueを維持し、selfHostExternalUrlを使用してください。プレイヤーへの自動配信とリモートホストへの切り替えを維持できます。

ItemsAdderはインストールしているのに、最終パックにそのコンテンツが含まれない​

これは通常、ItemsAdderの設定がResourcePackManagerによる読み取りやホストを妨げている状態であることを意味します。

次を使用してください：

/rspm itemsadder configure

このコマンドは現在、次のことを行います：

  • resource-pack.hosting.no-host.enabled を有効化します
  • protection_1、protection_2、protection_3 を無効化します
  • resource-pack.zip.compress-json-files: false を設定します
  • /iareload、続いて /iazip を実行します
  • RSPMが再生成されたItemsAdderのエクスポートをマージするのを待ち、マージが成功したかどうかを報告します

ResourcePackManagerはリロードされません。マージのメッセージの後、/rspm status でホスティングを確認してください。

「ItemsAdderはすでに自身のパックをホストしている」と表示された場合は、まず手動でItemsAdderのホスティングを無効化し、コマンドを再度実行してください。

マージされたパックが無効、またはアップロードに失敗する​

ResourcePackManagerの自動ホスト統合は、次のサーバー側エラータイプを明示的に処理します：

  • 必須ファイルの欠落
  • ファイルサイズ過大
  • 無効なファイル形式
  • セッションの欠落
  • リモートサーバーに到達できない

RSPMはアップロード前にファイルサイズの上限を自ら確認します。50,000 KiB（51,200,000バイト）を超えるJavaパックはアップロードされず、コンソールに Automatic hosting skipped: resource pack is <size> bytes; the limit is 51200000 bytes. と表示されます。その後RSPMは代わりに検証付きセルフホストを試します。セルフホストを参照してください。

これらが発生した場合：

  1. /rspm reload を実行してパックを再構築します。
  2. ソースパックのいずれかが壊れていたり、暗号化されていたり、その他の理由で読み取れなくなっていないかを確認します。
  3. 最終的にマージされたパックのルートに有効な pack.mcmeta と pack.png が残っているかを確認します。

有効化されたパックを展開またはステージングできない場合、現在のミックスは中断され、コンソールが失敗したパックの名前を表示します。そのパックを修復するか、手動で追加したZIPを削除するか、自動統合の設定で isEnabled: false を設定してからリロードしてください。

オーバーレイのメタデータとアーカイブ構造​

最終マージでは、formats、min_format、max_formatや追加メタデータなど、作者が指定したオーバーレイの形式宣言を保持します。同じオーバーレイディレクトリを共有する場合は、優先度の高いエントリを採用します。

書き換えが1つだけ行われます。Minecraft 1.21.9以降は、リスト内のいずれかのオーバーレイがパックフォーマット64以下に達し、別のオーバーレイがformatsを宣言していない場合、pack.mcmeta全体を拒否します。それぞれ単体では有効な2つのパックでも、オーバーレイのリストを結合するとこのルールに反することがあります。マージ後のリストに下限が64以下のオーバーレイが含まれる場合、RSPMはmin_formatとmax_formatだけを宣言している各エントリにformatsの範囲を追加します。この範囲はエントリ自身の境界と同じクライアントを対象とし、64以下から始まる場合は上限が64になります。衝突ログにはAdded the formats range to N overlay entriesと記録されます。すでにformatsを宣言しているエントリや、境界を解析できないエントリはそのまま残ります。それ以外で、RSPMが異なる世代のクライアント向け範囲を統一したり、無効な宣言を修復したりすることはありません。互換性のないメタデータはソースパックで修正してください。

RSPMは、オーバーレイのディレクトリが空でない相対パスであり、構築したパックのルート内に収まるかを確認します。絶対パス、正規化するとルート外に出るパス、無効なパスは拒否します。この確認に通っても、Minecraftが名前や形式メタデータを受け付けるとは限りません。

Pack Name/assets/とPack Name/pack.mcmetaを含むZIPには、余分な外側のディレクトリがあります。RSPMが警告するため、assets/とpack.mcmetaがZIPのルートに来るように圧縮し直してください。重複データを共有するアーカイブはセントラルディレクトリを通して読み込み、圧縮データを共有するエントリやテクスチャのアニメーションメタデータを保持します。

ブロックアトラスのテクスチャ​

マージされたブロックアトラスは、ディレクトリソースをパック内の具体的なPNGリソースに展開し、ソースの順序とスプライトIDを保持します。必要なミップレベルに適さないアニメーションフレーム寸法のテクスチャには、最近傍法で拡大した決定的なコピーをresourcepackmanager_internal:mip_safe/内に作成します。元のファイルはフォントなど他のローダー向けに変更せず残します。

予約済みのresourcepackmanager_internal名前空間にはコンテンツを作成しないでください。衝突すると拒否されます。これはJavaからBedrockへの変換ではなく、すべてのカスタムクライアントシェーダーやアトラス拡張への対応を保証する処理でもありません。

壊れたパックによる継続的な配信停止を防ぐ仕組み​

ステージングできないパックは毎回同じように失敗するため、放置すると配信が恒久的に詰まってしまいます — マージは完了せず、同じエラーが際限なく繰り返されます。同じファイルが3回連続で失敗した後、RSPMは残りのパックが出荷できるようにそのパックをマージから外し、その旨を1回だけ大きく通知します：

[ResourcePackManager] Resource pack X.zip failed to stage 3 times in a row and has been excluded
from the merge so the remaining packs can be delivered. The merged pack is now INCOMPLETE ...

これは文字どおりに受け取ってください：プレイヤーが受け取っているパックは、そのプラグインのコンテンツを欠いたものになっています。よくある原因は、壊れているか書き込みが途中で終わったzipです。

この除外は自動的に解除されます。失敗の記録はファイルのサイズと更新時刻をキーにしているため、ファイルを修復または置き換えれば隔離は自動的に解除され、次のマージでパックが復帰します — コマンドも再起動も不要です。/rspm reload もすべての隔離記録をゼロからリセットします。3回に達しなかった失敗カウントは、ミックスが1回成功するたびに破棄されるため、長い稼働時間にわたって散発した無関係な一時的トラブルが積み上がって除外に至ることはありません。

リモート自動ホストから SESSION_NOT_FOUND エラーが返ってきた場合、RSPMはセッションUUIDをクリアし、次のキープアライブティックで再初期化します — 手動介入は不要です。

あるプラグインのアセットが別のプラグインのアセットを上書きしている​

これは次のファイルにある priorityOrder で制御されます：

plugins/ResourcePackManager/config.yml

上位のエントリが下位のエントリに勝ちます。

マージ不可能なファイルでは、ResourcePackManagerは優先度の低いファイルを置き換えます。マージ可能なJSONファイルでは、内容をマージします。現時点でマージ可能なJSONのカテゴリは次のとおりです：

  • sounds.json
  • 言語ファイル
  • minecraft/models/item 配下のバニラのアイテムモデルJSON（非再帰的マージ：パックをまたいで overrides 配列のみが結合され、ファイルの残りの部分は最優先のパックが勝ちます）
  • アトラスファイル
  • フォントファイル
  • items/ 配下の1.21.4以降のアイテムモデル定義（predicateツリーの構造を尊重するフォーマット対応マージ）

pack.mcmetaにも専用のマージ処理があります。最も高いpack_formatを採用し、宣言されたパック形式の範囲を統合します。オーバーレイの範囲と追加メタデータは保持し、同じディレクトリには優先度の高いエントリを使用します。唯一の追加処理は、結合したリストが1.21.9以降のクライアントで読み込めるよう、必要なエントリにformatsの範囲を付与することです（オーバーレイのメタデータを参照）。それ以外でRSPMが作者の互換性のないメタデータを修復することはありません。他の競合しないメタデータも保持します。ベースのアトラスソースをオーバーレイのアトラスにマージし、ベースのエントリが隠れないようにします。

直近のマージで何が起きたかを確認したい場合は、次を確認してください：

plugins/ResourcePackManager/collision_log.txt

GUIテキストやフォントベースの要素が崩れて見える​

フォントファイルはResourcePackManagerがマージするJSONカテゴリの1つですが、それでも2つの異なるフォントシステムがMinecraft上でうまく共存するとは限りません。

フォント駆動のメニューやHUDがおかしい場合：

  1. 勝たせたいパックが上に来るように priorityOrder を変更します。
  2. /rspm reload を実行します。
  3. 期待した場所で衝突が起きたかを collision_log.txt で確認します。

リソースパックの変更がすぐに反映されない​

ResourcePackManagerには、対応するパックソース向けのウォッチドッグがあります。

変更されたパックが3秒間変化しなくなるまで待ち、すべての監視対象パックが安定した時点で即座に再ミックスが行われます。

別プラグインのパックを能動的に再生成している場合は、ファイル書き込みが止まってから数秒待ってみてください。判断に迷う場合は、上流のプラグインの処理が終わってから /rspm reload を実行してください。

/rspm status がリモートホスティングと表示するが、セルフホストを期待していた​

preferSelfHost: true（既定）でセルフホストの検証に失敗すると、この状態になることがあります。到達性チェックは詳細レベルで記録され、verboseLogging: true にしない限り表示されません。一部のメッセージには「This is OK.」が付きます。リモートホストが成功した場合の結果は Resource pack is live via automatic hosting — ... です。無効な設定、HTTPリスナーやリモート通信の失敗では警告が出ることもあります。

3つのレイヤーのどれが失敗したかを見るには、/rspm verbose on（または verboseLogging: true の設定）と /rspm reload を実行してください：

  1. Layer 1（ヒューリスティック） — 解決された外部ホストがRFC1918／ループバック／リンクローカルでした。selfHostExternalHost を実際の公開ホスト名に設定するか、プラグインが api.ipify.org ／ checkip.amazonaws.com に到達できるようにしてください。
  2. Layer 2（ローカルと通知URLのダウンロード） — http://127.0.0.1:<port>/rspm.zip とプレイヤー用の正確なURLから先頭の最大1 KiBを取得し、両方をローカルパックと比較します。HTTP 200または206、報告された長さの一致、206の場合は期待した Content-Range が必要です。リダイレクト、異なるバイト、ファイル欠落、サーバー側のNATループバック障害ではセルフホストを拒否します。
  3. Layer 3（外部到達性プローブ） — magmaguy.comが通知URLにHTTP 200または206で到達できたと報告する必要があります。HTTPポート閉鎖、リクエスト失敗、プローブサービスの利用不可では自動セルフホストを拒否します。ステータスと返された理由コードは verboseLogging で表示されます。

推奨順に、ファイアウォールとルーターでHTTPポートを開く、selfHostExternalHostに到達可能なホスト名を指定する、またはpreferSelfHost: falseでリモートホストを先に試す設定にしてください。セルフホストを代替経路としても使わない場合は、selfHostEnabled: falseも指定し、selfHostForce: falseを維持します。

プローブサービスに到達できない場合、セルフホストは未検証のままとなり、RSPMはリモートホストを試します。リモート失敗後のフォールバックでも同じセルフホスト検証が必要です。検証を省略できるのは selfHostForce: true だけで、両方の自動経路が失敗した場合は新しい配信URLを通知できません。プローブ成功でも、すべてのプレイヤーのネットワークからの完全なダウンロードとパック受け入れは証明できません。

完全な判定ツリーはセルフホストを参照してください。

自動ホストがリモートサーバーに到達できない​

ResourcePackManagerの組み込みリモートホストは次に通信します：

https://magmaguy.com/rsp/

この接続に失敗すると、プラグインは通信警告をログに出力し、再接続が成功するまでリモートフォールバックを使用できません。

選択肢は次のとおりです：

  1. サーバーの外向きHTTPS接続を修復する
  2. リモートサービスが再び到達可能になるのを待つ
  3. autoHost を無効にして、生成されたzipを自分でホストする
  4. HTTPポートを開け、selfHostExternalHost に公開ホスト名を設定し、preferSelfHost: true を維持する。明示した名前は公開IP自動検出を省略しますが、ローカル、通知URL、外部の各検証には合格する必要があります。プローブサービスに到達できない場合、自動セルフホストは選択できません。

マージされたパックを自分のWebサーバーでセルフホストしたい​

コードがサポートする手順は次のとおりです：

  1. autoHost: false に設定します。
  2. ResourcePackManagerに既存のフォルダーへ追加のコピーを書き込ませたい場合は、resourcePackRerouting を設定します。
  3. ResourcePackManager_RSP.zip を自分でホストします。

resourcePackRerouting は plugins ディレクトリからの相対として解決され、対象フォルダーは事前に存在している必要があります。

その代わりにRSPM組み込みのセルフホストHTTPサーバー（別物 — プラグインと同じJVM）を使いたい場合は、セルフホストを参照してください。

このサーバーについて保存されているリモートデータを確認したい​

次を使用します：

/rspm data_compliance_request

アクティブなリモートホスティングセッションがあれば、ResourcePackManagerは応答を次の場所にダウンロードします：

plugins/ResourcePackManager/data_compliance/data.zip

RSPMは同じ data_compliance フォルダーに ReadMe.md も書き出します。

リモートセッションがない場合（例：セルフホスト中）、コマンドはリクエストできるリモートデータがないことを伝えます。

Bedrockパックが生成されない​

bedrockConversionEnabled は既定で true のため、自動的に動作するはずです。まず /rspm status を実行してください — 「Bedrock Pack」セクションが、パックがディスクにない理由を教えてくれます：

  • 「No Bedrock target detected」 — ローカルのGeyser-Spigotもローカルの Floodgate もなく、ネットワークモードでもありません。変換は意図的にスキップされます。Floodgate（プロキシ構成向け）またはGeyser-Spigot（スタンドアロン構成向け）をインストールし、/rspm reload してください。
  • 「Network mode is active so this backend SHOULD produce a Bedrock pack. The file is missing」 — 通常は最初のミックスサイクルがまだ完了していない（起動後 ~30 秒待つ）、変換が変換可能なアイテムマッピングも許可されたエンティティバンドルも見つけられなかった、または変換が例外を投げたかです。コンソールで [BedrockConverter] の警告を探してください。bedrockConverterDebug: true の場合、スキャナーは Generic scanner: discovered N item definitions もログに出力します。件数が0なら、マージされたパックに変換可能なアイテム定義がありません。（状態の診断表示では、この行を discovered 0 items definition files として引用しています。）

Geyserの自動検出に失敗する場合：

  1. config.yml の bedrockGeyserFolder をGeyserのデータフォルダーへのパス（例：Geyser-Spigot）に設定します。
  2. 絶対パスはそのまま動作します。相対パスはまずサーバーの作業ディレクトリから、次に plugins ディレクトリからの相対として試されます。

コンバーターは plugins/Geyser-Spigot/、plugins/Geyser-*/ の任意の派生、または Fabric／NeoForge構成向けの config/Geyser-*/ で自動検出を試みます。

アイテム単位／ボーン単位のログ出力が必要な場合は、bedrockConverterDebug: true に設定してリロードしてください。

Bedrock：レガシーパックが存在するためライブプロバイダーがスキップされた​

コンソールが Legacy RSPM Bedrock pack detected を報告した場合、Geyserは起動時に自身のパックディレクトリにある古い ResourcePackManager_Bedrock.zip をすでにスキャンしています。プロセスの実行中にそのファイルを削除すると、Geyserは存在しないパスに対するコーデックをメモリ上に保持したままになるため、RSPMはその起動についてライブパックプロバイダーを意図的にスキップします。

サーバーを完全に停止し、RSPMが出力した正確なレガシーファイルのパスだけを削除してから、サーバーを再起動してください。この移行に /reload を使ってはいけません。現在のパックは plugins/ResourcePackManager/output/ に残り、セッション単位で配信されます。Geyserの packs/ ディレクトリに置くべきものではありません。

Bedrockプレイヤーで持ち物アイテムが正しくない位置に表示される​

まず、Bedrockクライアントを再接続して現在のパックを受け取らせ、意図したモデルと最新のパックが読み込まれたことを確認してください。RSPMは手持ちのポーズをJavaモデルのdisplay.firstperson_righthandとdisplay.thirdperson_righthandのトランスフォームから求めるため、Javaでもポーズがおかしい場合はJavaモデルで修正します。Javaでは正しくBedrockではおかしい場合は、モデルファイルを添えて報告してください。

bedrock_display_offsets.ymlとそのオフセット設定は削除され、現在は読み込まれません。古いコピーを編集しても効果はありません。手持ちアイテムのポーズを参照してください。

Bedrockプレイヤーでカスタム防具のテクスチャが表示されない​

カスタム防具は、バニラの防具ジオメトリにJavaのテクスチャを可視レイヤーとして重ねることでBedrock上に描画されます。これが機能するためには、ソースとなるプラグインのパックがアイテム定義と一緒に assets/<namespace>/equipment/<material>.json という装備ファイルを定義している必要があります。変換ログにそのアイテムが出ているのにゲーム内で防具テクスチャが見えない場合は、そのファイルがマージされたパックの中に存在するかを確認してください。

プロキシ：バックエンドがネットワークキーを持っていないと言う​

バックエンドで /rspm status が Network key source: not set — the proxy sends one when a player next connects here を示し、コンソールが「This backend is behind a proxy but has no network key yet」を繰り返します。

plugins/floodgate/key.pem がないことは原因ではありません — そのファイルは今や任意です。キーを所有しているのはプロキシです：プロキシは自身の network-key ファイルを読み込むか、Floodgateの key.pem があれば一度だけそこからシードするか、新しいキーを生成し、そのうえでプレイヤーが接続した時点で各バックエンドへプッシュします。

次の順で確認してください：

  1. プロキシの起動後、そのバックエンドにプレイヤーが接続しましたか？ 付与はプレイヤーの接続に乗って届きます。
  2. プロキシに実際に ResourcePackManager.jar が入っていますか？ バックエンドは plugins/ResourcePackManager/proxy-extension/ResourcePackManager.jar に自身のjarのコピーを用意し、そのパスを出力します — それをプロキシの plugins/ にコピーして、プロキシを再起動してください。
  3. モダン転送を使うVelocityでは、バックエンドの転送シークレットはプロキシのものと一致していますか？ モダン転送のバックエンドは、署名なしまたは誤って署名された付与を意図的に拒否します。どちらのケースかはログに書かれています。両側でシークレットを修正すれば、次のプレイヤー接続で自動的に再試行されます。
  4. 両側の/rspm statusでNetwork key fingerprintを比較してください。一致すれば同じネットワーク識別情報を使っています。接続性は取得結果で確認してください。キー自体は表示されません。

手順の全体はプロキシネットワークを参照してください。

/rspm statusにNetworkSync isn't runningと表示され、Floodgateのkey.pem不足を示唆する場合は、それ以前の起動エラーを読んでください。この補足は古い情報です。現在のプロキシはFloodgateなしでキーを生成・保存できます。初期化エラー、ファイル権限、バックエンドへの接続性に基づいて次の確認を進めてください。プロキシの/rspmコマンド自体が存在しない場合は、起動ログでネットワークIDの失敗を確認してください。

公開後のロールバックが不完全な場合​

Bedrock パック、プロキシの受信データ、または統合パックの公開に失敗し、以前のファイルを完全に復元できない場合、RSPM は復旧用コピーを保持し、そのディレクトリと影響を受けた保存先をログに記録します。不完全な成果物を使用対象から外す処理も試みます。記録されたディレクトリを保持し、ファイルシステムのエラーを解決して、パックとマッピングの整合性を確認してから再試行してください。ロールバックの失敗は公開の成功ではありません。

プロキシ：「Could not establish persistent RSPM network identity」​

現在のリリースは、保存されていないキーでは動作しません。プロキシが新しく決定したキーを network-key に保存できない場合や、既存の network-key ファイルを読み取れない場合、プロキシの役割は起動中に Could not establish persistent RSPM network identity: ... または Cannot read established RSPM network identity で停止します。ネットワーク同期、Bedrock配信、プロキシの /rspm コマンドは起動しないため、バックエンドは次回の再起動で変わる可能性のあるキーにリンクされるのではなく、既存のキーを保持します。

プロキシプラグインのデータフォルダー（Velocityでは plugins/resourcepackmanager/、BungeeCordでは plugins/ResourcePackManager/）のファイルシステム権限を修正してから、プロキシを再起動してください。読み取り可能な不正な形式の network-key ファイルは自動的に置き換えられます。

プロキシ：数回のポーリングサイクル後に「no merged pack」が表示される​

まず/rspm statusで確認済みRSPM参加バックエンドの数を見てください。参加が確認されていない新規プロキシは、登録済みサーバーすべてを故障したRSPMバックエンドとは扱わず、バックエンドの検出を継続します。未確認のサーバーがパック同期を遅らせることはありません。

確認済みの参加バックエンドがあり、4回連続のポーリングで内容を取得できないと、参加先、試行したHTTP URL、取得結果を示す診断が出ます。既定の間隔は5秒ですが、ネットワーク処理によって経過時間が延びる場合があります。診断には主な対処方法も表示されます：

  • すべてのバックエンドで CONNECT_FAILED → プロキシがバックエンドのHTTPポートに到達できません。velocity.toml ／ config.yml のアドレスがプロキシから実際に到達可能なもの（プロキシのネットワークから解決できないDockerの内部名などではない）であること、そしてバックエンドが通知したHTTPポートがプロキシとバックエンド間で開いていることを確認してください。バナーは試行した正確なURLを表示します。バックエンドがポートを通知する前は、プロキシは mcPort + network-http-offset-v2 にフォールバックするため、早い段階での CONNECT_FAILED は、そのフォールバックポートがまだ到達不能であることを意味する場合もあります。
  • すべてのバックエンドで NOT_FOUND_404 → バックエンドは起動していますが、Bedrockパックを生成していません。各バックエンドで /rspm status を実行してください。Bedrock Packの診断ブロックが理由を教えてくれます。

バナーは詰まった期間ごとに1回発火し、少なくとも1つのバックエンドがコンテンツを返すようになると「NetworkSync: recovered」行がログに出力されます。詳細はプロキシネットワークを参照してください。

プロキシ：初回プロキシ起動時にBedrockプレイヤーにモデルが見えない​

Geyserはプロキシ起動時にだけカスタムアイテムテーブルを登録します。Bedrockパックを生成したバックエンドより先にプロキシが起動した場合、Geyserは空のマッピングテーブルで動作し、そのセッションの残り時間ずっとそのままになります。

プロキシにMerged Bedrock pack published at ...が記録された後で、プロキシを再起動してください。RSPMは起動時に前回のマッピングを事前配置するため、次回以降は保存済みのマッピングを登録できます。起動後に新しい識別子が追加された場合は、再びこの再起動が必要になることがあります。

バックエンド：「Backend HTTP server failed to bind on port X」​

ネットワークモードでは、バックエンドは小さなHTTPサーバー経由でBedrock出力を公開します。ポートが使用中または利用不可の場合、コンソールに複数行の [ERROR] ブロックが表示されます。修正：

  • config.yml で selfHostPort を別の正の値に設定します。
  • または networkHttpOffset-v2 を変更して、自動導出されるポートを衝突から離します（例：RCONが mcPort + 1？ 2か3に設定します）。プロキシを合わせて更新する必要はありません：バックエンドが正常にバインドすると、実際のHTTPポートをプロキシに自動通知するため、プロキシ自身の network-http-offset-v2 は通知前の推測としてのみ意味を持ちます。

バックエンドのHTTPサーバーがダウンしている間は、このバックエンドのBedrockパックは直接取得ではプロキシに届きません。magmaguy.com のリレーフォールバックは引き続き動作します（バックエンドがファイルをリレーにプッシュし、プロキシはそこ経由で取得します）。

古い v1 設定のクリーンアップ​

RSPM v1からアップグレードするオペレーターは、config.yml に死んだ networkHttpOffset（-v2 なし）キーが残っているかもしれません。RSPM v2は意図的に古いキーを読みません — 次回起動時にv2の既定値（1）が自動的に設定に書き込まれます。死んだv1キーは無害な遺物として設定ファイルに残るので、手動でクリーンアップしてください。