WSL2 + Docker + Supabase トラブルシューティングガイド
背景
WSL2環境でSupabase Localを使用していると、Dockerコンテナの起動失敗時にポートが解放されず、再起動しても問題が解決しないことがあります。本記事では、2026年3月に発生した一連のトラブルとその解決方法を記録します。
発生した問題
問題1: ポートが既に使用中
failed to start docker container: Error response from daemon: failed to bind host port for 0.0.0.0:54324:172.20.0.7:8025/tcp: address already in use
原因: Supabaseコンテナが正常に停止されず、docker-proxyプロセスが孤立して残っていた。
問題2: Docker再起動後もポートが解放されない
sudo systemctl restart docker を実行しても、docker-proxyが再生成される。
原因: /var/lib/docker/network/files/local-kv.db に孤立したネットワーク設定が残っていた。
問題3: iptablesチェーンが存在しない
iptables v1.8.10 (nf_tables): Chain 'DOCKER-ISOLATION-STAGE-2' does not exist
原因: WSL2のUbuntuでiptablesがnftablesバックエンドを使用しており、Dockerと互換性がなかった。
解決手順
Step 1: iptablesをlegacyモードに切り替え（恒久対策）
sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
Step 2: nftablesのルールをクリア
sudo nft flush ruleset
Step 3: Dockerを完全にリセット
# DockerとSocketを完全に停止
sudo systemctl stop docker.socket docker
# 孤立したdocker-proxyを全てkill
sudo pkill -9 -f docker-proxy
# Dockerのネットワーク設定を削除
sudo rm -rf /var/lib/docker/network
# Dockerを再起動
sudo systemctl start docker
Step 4: Supabaseを起動
npx supabase start
予防策
1. Supabaseは必ず正しく停止する
# 推奨
npx supabase stop
# バックアップ不要な場合
npx supabase stop --no-backup
やってはいけないこと:
-
Ctrl+Cで強制終了 - ターミナルをそのまま閉じる
- PCをシャットダウン/スリープさせる（コンテナ稼働中）
2. package.jsonにスクリプトを追加
{
"scripts": {
"db:start": "supabase start",
"db:stop": "supabase stop --no-backup",
"db:reset": "supabase stop --no-backup && supabase start"
}
}
3. トラブル発生時用のリセットスクリプトを用意
~/bin/docker-reset.sh として保存:
#!/bin/bash
set -e
echo "Stopping Docker..."
sudo systemctl stop docker.socket docker
echo "Killing orphaned docker-proxy processes..."
sudo pkill -9 -f docker-proxy 2>/dev/null || true
echo "Clearing Docker network config..."
sudo rm -rf /var/lib/docker/network
echo "Starting Docker..."
sudo systemctl start docker
echo "Docker reset complete!"
実行権限を付与:
chmod +x ~/bin/docker-reset.sh
4. 作業終了時のチェックを習慣化
# コンテナが残っていないか確認
docker ps
# 何もなければOK
5. エイリアスを設定（~/.bashrc）
# Supabase用コマンド
alias sb-start='npx supabase start'
alias sb-stop='npx supabase stop --no-backup'
alias sb-clean='npx supabase stop --no-backup 2>/dev/null; ~/bin/docker-reset.sh'
クイックリファレンス
| 症状 | コマンド |
|---|---|
| ポートが使用中 | sudo pkill -9 -f docker-proxy && sudo systemctl restart docker |
| Docker再起動でも解決しない | sudo rm -rf /var/lib/docker/network && sudo systemctl restart docker |
| iptablesエラー | sudo nft flush ruleset && sudo systemctl restart docker |
| 全部ダメ | ~/bin/docker-reset.sh |
環境情報
- OS: Ubuntu (WSL2)
- Kernel: 6.6.87.2-microsoft-standard-WSL2
- Docker: 28.4.0 / 29.3.0
- iptables: v1.8.10 (legacy)
- Supabase CLI: npx経由
参考
- WSL2ではDockerの状態が壊れやすい
- iptablesはlegacyモードの方がDockerとの互換性が高い
-
docker.socketが有効だと、Dockerへのアクセス時に自動起動される