トラブルシューティング

以下の症状から該当するものを探してください: herdr plugin からの Os { NotFound } · update に "not currently on a branch" と表示される · tailscale serve failed · 応答しない (サービスが起動しない) · スマートフォンで URL を開けない · ページは読み込まれるが表示されない (白画面、403) · パスワードプロンプトに入力できない · プッシュ通知が届かない · 再起動後に消える · ペインが狭いまま固定されている · Collie が tmux ウィンドウを開かない · tmux list: output did not parse · herdr plugin list に古いバージョンが表示される · 再ビルド後も UI が古いままになる。

herdr plugin …がError: Os { code: 2, kind: NotFound, message: "No such file or directory" }で失敗する (プラグインのインストールに失敗する、アクションの実行に失敗する). これはCollieの問題ではなくありません。Herdrサーバーが動作していないため、そのCLIがコントロールソケット(~/.config/herdr/herdr.sock)にアクセスできていません。判断の決め手となるのは生の Os {…}エラーです。サーバーにアクセスできる状態であれば、パスやマニフェストの問題に対して構造化JSON(例: plugin_manifest_not_found)で応答するため、単なるOs { NotFound }エラーが出るのは、Collieやパスの検証が行われる前にソケット接続自体が失敗していることを示します。この問題は、link、install、action invokeなど、サーバーと通信するすべてのサブコマンドで発生しますが、herdr plugin --helpは動作します(ソケットを開かないため)。対処法: 先にHerdrを起動し(herdr server &、またはサーバーを起動するHerdr TUIを立ち上げる)、ls ~/.config/herdr/herdr.sockが存在することを確認してからインストールを再試行してください。herdr plugin listで簡単に確認できます。同じエラーが発生する場合はサーバーが停止しています。

updateがYou are not currently on a branchで失敗します。 0.23.1(#63)以前に行われたGitHubインストールでの問題です。クローンではなくherdr plugin installのデタッチが行われたため、古いupdateにはgit pull先のブランチがありませんでした。修正内容は修正対象のチェックアウト内に含まれているため、適用するには一度再インストールが必要です。必要な3つのコマンドは"You are not currently on a branch" で失敗する場合に記載されています。

startがnote: tailscale serve failedを出力します。 Collie自体は問題ありません（127.0.0.1 で稼働中）。tailnetのingressが起動しなかっただけであり、Tailscale自体のエラーはメッセージの上のターミナルに表示されています。主な原因は、実行ユーザーがTailscaleのoperatorではない（sudo tailscale set --operator=$USER）、ノードがログアウトしている（tailscale up）、またはHeadscale / .internal tailnetドメインでHTTPS証明書が利用できないことです。まさにそのために COLLIE_SERVE_MODE=http が用意されています。.env に設定し、bin/collie restart を実行してください。tailscale serve status で確認します。

serve には HTTPS certificates are not enabled on this tailnet と記載されています。 公開されたものはなく、待機中のものもありません。admin console を開き、「Enable HTTPS」を有効にしてから、collie serve を再実行してください。Headscale / .internal ドメインには有効化する証明書が存在しないため、代わりに COLLIE_SERVE_MODE=http を使用してください。

バナーに⚠ Collie isn't answering on :8787 yetと表示される (サービスが起動しない、connection refused). サービスは開始されましたが、HTTPサーバーがプローブに応答していません。まずユニットを確認し(systemctl --user status collie)、次に原因をbin/collie logs(またはリアルタイム監視ならjournalctl --user -u collie -f)で確認してください。最も多い原因はポートの競合(.envでCOLLIE_PORTを設定し、bin/collie restartを実行。新しいポートに対してtailscale serveも再実行されます)、または初回ビルドの失敗です(ログに記載されます。修正してbin/collie buildを実行してください)。ユニットは5秒ごとに自動再起動するため、原因を解決すれば通常は自動で復旧します。

スマートフォンからtailnet URLを開けない。 次の項目を順に確認してください: (1) スマートフォンでTailscaleアプリが動作しており、ホストと同じtailnetに接続されていること。(2) バナーのtailnet URL(bin/collie url)を開いており、localのURLではないこと(http://127.0.0.1:8787はホスト自身でしか機能しません)。(3) tailnetのDNS設定でMagicDNSが有効になっていること(URLはMagicDNS名です)。(4) ホストがオンラインであること(ホスト側でtailscale statusを確認するか、スマートフォンのTailscaleアプリからホストにpingを実行)。(5) tailnetのポリシーでピアからこのノードへの通信が実際に許可されていること。許可されていない場合、バナーのtailnet行の下にその旨が表示されます。これ以外の方法では判別できません。入り口は正しく公開され、証明書も有効で、ホスト自身からのcurlは200を返します(ループバックはパケットフィルターを通らないため)。この問題を特に見誤りやすくしている要因が2つあります。tailscale pingが成功すること(disco pingはACLをバイパスします)、そしてブロックされたトラフィックは拒絶(refuse)ではなく破棄(drop)されるため、スマートフォン側では単にタイムアウトして「サーバー停止」のように見えることです。ACLポリシー(Tailscaleの場合は<https://login.tailscale.com/admin/acls>、Headscaleの場合はポリシーファイル)で修正してください。この確認機能はベストエフォートであり、過信は禁物です。このノードのフィルターが何も許可していないを許可している場合にのみ警告を表示しますが、これは他のデバイスがまだtailnetに参加していないだけの可能性もあります。判断できない場合は何も表示しません。

ページは読み込まれるが表示されない (白画面、コンテンツが表示されない); API呼び出しが403 cross-origin rejectedで失敗する。 想定外のオリジン(カスタムドメインや、Hostを書き換えるプロキシなど)経由でCollieにアクセスしています。COLLIE_ALLOWED_ORIGINSで正確な公開オリジンを許可するか(設定を参照)、プロキシがHostを変更せずに転送するように設定してください(docs/deployment.mdの4つ目のプロキシ要件)。

sudo(またはSSHパスフレーズ、gpg)のプロンプトで応答が受け付けられない。 Sendではなく、Controls行のTypeを使用してください。SendはEnterを押す前に画面から読み戻すことで入力内容を検証しますが(34)、パスワードプロンプトではエコーバックが無効になるため、読み戻すものが存在しません。TypeはEnterも含めてキーストロークを直接ペインに送信します。Typeに入力した内容は保存されず、下書きに反映されることも、後から復元されることもありません。また、Collieがパスワードプロンプトを認識した時点で、保存されていた下書きも破棄されます(103)。

プッシュ通知が届かない。 手動で送信をテストしてください: bin/collie push-test。エラー原因はコマンドの出力順に3つあります。pushが無効と表示される(鍵がブリッジに届いていません。push-keysを実行して再起動してください。Web Pushを参照)、購読デバイスがないと表示される(このスマートフォンで設定 → 通知が有効になっていません)、または送信完了と表示されるのに届かない(スマートフォンがセキュアコンテキストではない平文HTTPオリジン上にあります。設定ではinsecureと表示されます)。

再起動後にCollieが停止している。 Linux ではほとんどの場合 lingering が原因であるため、loginctl enable-linger $USER を実行してください (再起動後も維持する)。macOS では launchd エージェントが ログイン で起動するため、実際にログインしていること (ログイン画面のままになっていないこと) と、エージェントがロードされていることを確認してください: launchctl print gui/$(id -u)/herdr.collie。

ペインのターミナルが狭いまま固定され、内部のフルスクリーンアプリが潰れて表示される（Copilot CLI、top、またはミラーの残りが空白のまま帯状に描画されるTUI）. ペインのターミナルが実際にその幅であり、Collieはその状態をそのままミラーリングしています。Herdrのペイン幅はタブ内の分割グリッドにおける矩形領域によって決まるため、タブを共有するペインは列数を分け合います。Herdrがペインのジオメトリを適用するのはデスクトップクライアントがアタッチされている間のみ（herdr#1709）です。何もアタッチされていない状態では、分割を閉じても残ったペインは以前の狭い幅のままになり、ソケット経由のpane.zoomやpane.resizeでも変更されません。Collie側からこれを修正することはできません。Collieはペインのジオメトリを一切書き込まないためです（ADR 0031、スマートフォンがオペレーターのターミナルを移動させるのはShow in terminalのタップ時のみです）。これは特定のアプリケーション固有の問題ではありません。54列のペインで実行したtopもまったく同じ表示になります。幅を測定するには、ペイン内でtput colsを実行してください。これが実際の幅であり、herdr pane layoutの報告する値とは異なる場合があります。修正するには、Herdrクライアントをアタッチしたうえでペインをズームまたはリサイズするか（クライアントがアタッチされていればherdr pane zoom <pane-id> --onによってターミナルが移動します）、ペインを閉じて新しく開き直してください（#167）。

Collie が tmux ウィンドウを開かない（スマートフォンの新規タブが拒否され、window-sizeが示される）. リクエストのエラーではありません。3.7未満のtmuxでは、サーバーのwindow-sizeがmanualのときにウィンドウを生成するとサーバー全体がクラッシュし（tmux #4849、3.7で修正済み）、全ウィンドウが巻き添えで消失します。そのためCollieは生成を拒否し、検出したtmuxのバージョンを表示します。対処法は、表示されたコマンド（そのサーバー上でtmux set -g window-size latest）を実行するか、tmux 3.7へ更新することです。他の操作には影響せず、対象ペインでのこれ以外の操作はすべて動作し続けます（要件にも同様の制約があります）。

Collieがtmux list: output did not parseを出力し、ダッシュボードに何も表示されない。 クラッシュではありません。一部のtmuxバージョン（3.6bではなく3.4など）では、-Fのリスト出力時にこのアダプターが読み取る区切り文字がエスケープされます。Collieは現在両方の形式を読み取るため、解析結果が0行になった場合は空のherdとして保存せずmuxエラーとして報告します。エラー行にはtmuxのバージョンと読み取った行数が表示されます。これが発生する場合は、tmux -Vのバージョンを確認してIssueを作成してください。修正はユーザー側の.envではなくアダプター側で行う必要があります。

updateの実行後もherdr plugin listに古いバージョンが表示される。 正常な動作です。Herdrはインストール時またはリンク時に読み取ったマニフェストをキャッシュします。現在実行中の内容の正式な情報は、フッターのビルドスタンプまたはbin/collie versionで確認できます。リンクされたクローンの場合、updateを実行すると再リンクされて自動修復されます（herdr plugin link "$(pwd)"で強制実行可能）。Herdr ≥0.8.0では、いずれにしてもマニフェストがディスクから再読み込みされます。

リビルド後、スマートフォンに古いUIが表示される。 PWAのService Workerキャッシュはオリジンごとに分かれています。そのため、2つのオリジン（カスタムドメインと生のhost:8787）からCollieにアクセスすると2つの環境がインストールされ、それぞれが独自のバンドルをキャッシュします。フッターのビルドスタンプ（vX.Y.Z · sha · time）は実行中のバンドルを示し、Collieが配信している内容はX-Collie-Buildヘッダーおよび/api/configで確認できます。不一致がある場合、フッターに「新しいビルドがあります — タップして更新」が表示されます。表示されない場合は、PWAを数回開き直すか（Service Workerが自動更新されます）、そのオリジンのサイトデータを削除してください。推奨事項: 使用するHTTPSオリジンを1つに固定してください。（平文HTTPではService Workerが登録できないため常に最新になりますが、PWAの機能は使えません。）