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

症状別の対処法です。エラーコードの網羅表は HTTP API リファレンスにあります。

アップロードが失敗する

`401 unauthorized`

MISERU_TOKEN が未設定・タイポ・失効済みのいずれかです
トークンはダッシュボードで失効(revoke)されると即座に使えなくなります。新しいトークンを発行して差し替えてください
CLI で MISERU_TOKEN が未設定です と出る場合は環境変数がプロセスに渡っていません(export MISERU_TOKEN=msr_... を確認)

`413 payload too large (max 5MB)`

画像は 5MB 未満が上限です(GitHub Camo の制限)
スクリーンショットの解像度を下げる、PNG → WebP/JPEG に変換する、フルページではなくビューポートのみ撮影する、などで縮小してください

`415 unsupported content-type`

対応形式は PNG / JPEG / WebP のみです。GIF・SVG・PDF などは送れません

`415 declared image/png, but the file content is not a valid PNG`

拡張子と中身が食い違っています。CLI / GitHub Action / ダッシュボード（ブラウザ）はいずれも Content-Type をファイル拡張子から決めるため、「中身は JPEG なのにファイル名が .png」だとこのエラーになります
正しい拡張子にリネームしてから再実行してください（中身が JPEG なら .jpg）
スクリーンショットツールが拡張子と異なる形式で保存していないか確認してください（例: .png で保存すると言いつつ実体は JPEG）
実体の形式に合わせてリネームした結果（例: 中身が GIF なので .gif にした）今度は unsupported content-type が出る場合、その形式は非対応です。PNG / JPEG / WebP のいずれかに変換してください

`429 rate limited`

プロジェクトあたり 120回/分のレート制限です。Retry-After: 60 に従って待ってから再試行してください
CI の並列ジョブから大量に送っている場合は、送信をまとめるか間隔を空けてください

`--sha を指定してください(git リポジトリ外のため自動検出不可)`

CLI は --sha 省略時にカレントディレクトリの git rev-parse HEAD を使います。git リポジトリの外から実行する場合は --sha <コミットSHA> を明示してください

PR に画像が表示されない

コメント自体が付かない

GitHub Action は設定しましたか? CLI / MCP の miseru push は markdown を返すだけで、コメント投稿は GitHub Action の役割です
ワークフローに permissions: pull-requests: write がありますか? ないとコメント投稿が失敗します
fork からの PR では、Action はコメント投稿をスキップします(トークンが読み取り専用のため)。Action のログに markdown が出力されているので手動で貼れます

コメントはあるが画像が壊れている

画像がすでに失効していないか、ダッシュボードで確認してください(失効済みバッジ)
pr_close ポリシーの場合、PR をクローズ → 再オープンしても画像は戻りません(失効は削除であり不可逆です)。再度アップロードしてください
5MB 以上の画像は GitHub Camo が表示しません(アップロード時に拒否されますが、api-url を差し替えた自己ホスト構成などでは起こりえます)

PR にコメントが2つ以上できる

Miseru のコメントは先頭のマーカー  で識別・更新されます。マーカーを含むコメントを編集してマーカーを消すと、次回から新規投稿されて重複します。マーカー行は残してください

失効まわり

失効させたのにまだ見える

失効はオリジン削除が即時で、以後の新規アクセスは必ず 404 になります。キャッシュされた表示(GitHub Camo)が切れるまでの時間はポリシーで異なります: PR クローズで失効は最大5分程度、N 日保持は保持期限まで、無期限の手動失効はキャッシュの保持期間中は残ることがあります
それより長く残る場合はブラウザキャッシュの可能性があります。強制リロードで確認してください
閲覧者の手元に保存された画像・スクリーンショットは制御できません(→ 配信とセキュリティの仕組み)

`retain_days` の期限が来たのに消えていない

期限切れ画像は毎時の自動スイープが削除します。実削除まで最大1時間程度のずれがあります
なお期限を過ぎた画像は、スイープ前でも配信キャッシュの許容期間が期限までに設定されているため、事実上表示は止まります

手動失効が `503 expire failed, retry later` になった

一時的な失敗です。その画像は失効予約としてマークされており、毎時の自動スイープが失効を完了させます。放置して問題ありません

ダッシュボードまわり

サムネイルが「読み込み失敗」になる

一覧のサムネイル URL は30分の短命署名です。タブを開きっぱなしにすると期限切れになります。「再読み込み」ボタンで回復します(画像の失効ではありません)

トークンの平文を控え忘れた

平文は発行時の一度しか表示されず、復元できません(サーバーはハッシュのみ保存)。古いトークンを失効させ、新規発行してください

ログインが切れる

セッションは 7日間です。切れたら再度 GitHub でログインしてください

よくある質問

Q. プライベートリポジトリでも使えますか? A. 使えます。Miseru は PR コメントに署名付き URL の画像を貼る方式なので、リポジトリの公開範囲に依存しません。ただし URL を知っていれば誰でも閲覧できる点は共通です(→ 秘匿性の限界)。

Q. 画像は誰に見えますか? A. URL を知っている人全員です。閲覧時の認可はありません(GitHub Camo の制約)。機密情報を含む画像はアップロードしないでください。

Q. GitHub App のインストールは必要ですか? A. 不要です。ログインは GitHub OAuth、PR コメントはあなたのリポジトリの GitHub Action(github.token)で行われます。

Q. 1つのトークンを複数リポジトリで使えますか? A. トークンはプロジェクト(リポジトリ)単位です。リポジトリごとにプロジェクトを作成し、それぞれのトークンを発行してください。