IrisBooks マニュアル
EN / 日本語
章一覧
マニュアル / トラブルシューティング
第10章

トラブルシューティング

よくある状況と解決法です。迷ったらまず iris validate を実行してください。何が おかしいかを知る一番速い方法です。

iris validate がエラーを出す

iris validate は全ファイルをチェックし、問題点を表示します。よくある原因:

  • 貸借不一致 — 借方と貸方が一致しない。合計が等しくなるよう金額を直します。
  • 未知の科目 — 仕訳が config/chart-of-accounts.yaml に無い科目を参照して いる。勘定科目表に科目を追加します（またはエイリアスを使う）。仕訳の中で 科目パスを勝手に作らないこと。
  • 日付の不一致 — date: フィールドがファイル名の YYYY-MM-DD 接頭辞と一致 しない。両者を合わせます。
  • 不正なステータス — status は draft または posted。
  • YAML が解析できない — たいていフロントマターのインデントか余分なコロン。 エラーがファイル名を示します。
  • 税区分（日本の課税事業者） — 未知の区分を持つ tax ブロックや、区分に 合わない税率（例：率の無い taxable_sale、率が0でない export_sale）。

直して再実行します。このループは AI アシスタントに任せられます。

「posted にしたのにレポートに出ない」

レポートに載るのは posted の仕訳だけです。iris balance・損益計算書・貸借 対照表に取引が出てこない場合、ほぼ確実にステータスがまだ draft です。昇格します。

iris post journals/2026/05/2026-05-04-example-com-01.md

…または status: フィールドを posted に編集して再検証します。

「iris: command not found」

iris バイナリがまだこのマシンの PATH にありません。インストールして （macOS / Linux は curl -fsSL https://irisbooks.jp/install.sh | sh、 Windows PowerShell は irm https://irisbooks.jp/install.ps1 | iex）、 iris version で確認します。サンドボックスの AI 環境で作業して いる場合、帳簿内に同梱コピーはありません。ホストが iris mcp serve を実行し、 アシスタントが各動詞を MCP 経由で呼び出します。

同期の拒否（needs-attention）

iris validate はファイルの状態をチェックしますが、push 時にはサーバーが追加の ルールを実行します（勘定科目射影の孤児、まだアップロードされていない raw/ ファイルを参照する仕訳、スキーマ/不変条件の違反）。サーバーが push を拒否すると、 iris validate の末尾に「N file(s) blocked in the sync queue」のような注記が出る ことがあります。ファイルは問題なく、push が拒否されたのです。

解消するには:

iris attention list      # フィールド単位の理由を読む

そして原因を直します。たいていは:

  • 不足している科目を config/chart-of-accounts.yaml に追加する、または
  • 参照している raw/... の資料が実際に存在し同期されているか確認する。

その後、拒否された仕訳を保存し直します。コンテンツハッシュが変わると、エンジン はファイル単位の抑制を外し、次回の同期で push が自動的に出ます。

修正が別のファイルにある場合（例：数日前に勘定科目表を直し、その仕訳はもう触らない） は、エンジンを促します。

iris attention retry            # キュー内すべてを再 push
iris attention retry --path <relpath>   # 1ファイルのみ

同期のコンフリクト

あなたと別の誰か（または別端末のあなた）が同じファイルを変更すると、push が コンフリクトすることがあります。サーバー版が正規パスを取り、あなたの版は <file>.conflicted サイドカーとして隣に保存されます。サイドカーが存在する間 iris sync は進行を拒否するので、何も失われません。

iris conflicts list

各件を解決します。通常は手動マージです。正規ファイルを開き、.conflicted サイドカーから必要な部分を取り込み、サイドカーを削除し、再度 iris sync を実行 します。どちらか一方を丸ごと採用するには:

iris conflicts resolve <path> --keep mine     # 正規をあなたの版で置換
iris conflicts resolve <path> --keep cloud    # あなたの版を破棄

iris sync が終了コード 3 で終わる

終了コード 3 は終端的切断を意味します。サマリー（および iris sync --json の disconnectReason フィールド）がどの種類かを示します。

  • deleted — オーナーがサーバー上の帳簿を削除しました（Web アプリ → 帳簿の設定 → 危険な操作）。ローカルのファイルは無事です — フォルダからは何も 削除されておらず、iris status に Remote: deleted on the server と表示され ます。ローカルで作業を続けるには、config/book.yaml の book_id をローカル ID に戻します（iris status が表示します）。クラウドに再接続するには、新しい帳簿を 作成し（iris api books new）、リンクします（iris api books link <id> --force）。
  • forbidden — アクセスが取り消されました（認証情報は有効ですが、権限が ありません）。帳簿のオーナーに再招待を依頼してください。意図的な取り消しで あれば、それは想定どおりです。
  • auth_expired — セッションが失効しました。再認証し（iris api login）、 iris sync を再実行してください。

「締め済みの年度を変えたい」

締め済み会計年度はロックされています。iris post はその年度の仕訳を拒否し （“FY <n> is sealed (closed period) — run iris reopen <n> to amend it, then re-seal”）、その年度への同期の push はサーバーが拒否し、Web アプリと リモートコネクタでの編集も拒否されます。年度のファイルは作業ツリーにそのまま 残っています — 書き込みが拒否されるだけです。修正するにはまず再オープンします。

iris reopen 2025      # 締めのロックを解除（ファイルは作業ツリーにそのまま）
# …訂正する…
iris sync
iris api seal --period 2025 <book-id>   # 年度を再度締める

サーバーは訂正を締め後の編集として記録します。アクティビティログに表示され、 Web アプリでバッジが付きます。これは設計どおりです。訂正は許可され、かつ監査可能 であり、隠されません。再度の締めは古い締めを監査チェーン上で引き継ぎます。

「Web アプリと CLI で数値が違う」

ほぼ必ず同期のずれかステータスの違いです。

  • iris diff で未 push のローカル変更を確認し、iris sync します。
  • Web アプリも CLI と同じく、レポートに載るのは posted のみです。ローカルで 見えている下書きは、posted にして同期するまで現れません。
  • Web アプリのレポートには、サーバーが最後に再計算した時刻の「鮮度」注記が出ます。 push 直後は射影されるまで少し待ってください。

それでも解決しないとき

  • 基本コンセプト を読み直してください。混乱の多くは status （下書き vs posted）か、同期が何をするかについてです。
  • 帳簿内の notes/open-questions.md を確認してください。AI は曖昧な項目をそこに 記録します。
  • 日本の税務の詳細は 日本の税務・コンプライアンス を参照。変わりうる値（税率・各種表・申告様式）は AI が国税庁の現行ページで 確認します。