FAQ & トラブルシューティング

gophertunnel を使用する際によく遭遇する問題と解決策をまとめています。

---

接続・認証関連

Q: invalid status (401 Unauthorized) や認証エラーが出る

• 原因: Xbox Live トークンの期限切れ、または PlayFab の認証チェーンエラー。
• 対処:
  1. キャッシュしているトークンファイル（token.json など）を一度削除し、再度 auth.RequestLiveToken() でブラウザ認証を行ってください。
  2. アカウントに Minecraft Bedrock Edition の正規ライセンスが紐付いているか確認してください。

Q: 外部サーバーに接続できない (i/o timeout / connection refused)

• 原因: Bedrock は UDP ポート（通常 19132）を使用します。ファイアウォールやルーターで UDP がブロックされていないか確認してください。
• 確認方法: minecraft.PingContext() を実行して、サーバーから Pong 応答が返ってくるかテストしてください。

---

パケット処理・エラー

Q: panic: ReadPacket called simultaneously from multiple goroutines

• 原因: minecraft.Conn の ReadPacket() はスレッドセーフではありません。
• 対処: ReadPacket() は必ず1つの goroutine のループ内で呼び出してください。複数の goroutine から同時に呼び出してはいけません。（※ WritePacket() は並行呼び出し可能です）

Q: unexpected packet (ID=...) で接続が切断される

• 原因: パケットプールに登録されていない未知のパケットを受信した。
• 対処:
  • Dialer.DisconnectOnUnknownPackets = false または ListenConfig.AllowUnknownPackets = true に設定することで、切断せずに packet.Unknown 型として受け取ることができます。

dialer := minecraft.Dialer{
    DisconnectOnUnknownPackets: false,
}

Q: decode packet: unread bytes left: ... が発生する

• 原因: Minecraft のバージョン更新等により、パケットに新しいフィールドが追加され、gophertunnel 側の構造体定義と差分が生じている。
• 対処: go get -u github.com/sandertv/gophertunnel@latest で最新版にアップデートしてください。

---

プロキシ・パフォーマンス

Q: プロキシ経由だとパケット送信が少し遅延する

• 原因: デフォルトの FlushRate が 50ms (time.Second / 20) に設定されているため、パケットがバッファリングされています。
• 対処: 即時反映させたい場合は、パケット送信直後に conn.Flush() を呼ぶか、FlushRate を 5ms〜10ms 程度に設定してください。

_ = conn.WritePacket(pk)
_ = conn.Flush() // バッファを即時フラッシュ