トラブルシューティング

このページは、遭遇しがちな失敗を発生箇所別に分類しています。各エントリは症状、推定原因、修正法を示します。

ここにない問題は、Agent にセッション内で聞くのが最速です — エラーを貼って説明を頼めば、通常診断してくれます。それ以外: support@tablize.com または Discord コミュニティ（フッターのリンク）。

はじめに

初回ロードで「503 Service Unavailable」

原因: Tablize がまだ初期化中。ドメインは初回リクエスト時に遅延ブートストラップされ、初回ページロードは最大 30 秒間 503 を返すことがあります。

修正: 30 秒待ってリロード。2 分以上続く場合:

• Cloud: status.tablize.com を確認。
• セルフホスト: docker logs tablize — マイグレーションエラーや env var の欠落を探してください。

マジックリンクのメールが届かない

原因: 通常はスパムフィルタリング。

修正:

1. スパム / プロモーションフォルダを確認。
2. no-reply@tablize.com を連絡先に追加。
3. セルフホスト: SMTP_* env vars を確認。docker exec tablize tablize-cli test-smtp でテスト。

データのアップロード

「File too large」

原因: ファイルがプランのアップロード上限を超過（Free 50 MB、Plus 200 MB、Pro 2 GB、Max 10 GB）。

修正:

• ファイルを小さなチャンクに分割して個別アップロード。Agent が UNION ALL できます。
• または Parquet に変換 — 同じ行、ディスク上で 5〜10 倍小さい。
• またはプランをアップグレード。

「Encoding error」/ 文字化け

原因: ファイルが UTF-8 を主張しているが、実際は Latin-1 / Windows-1252。

修正: ソースツールから UTF-8 で再エクスポート。Excel では: Save As → CSV UTF-8。

日付カラムがテキスト型になる

原因: ファイル最初の行が不整合またはロケール依存のフォーマット（例: 1/1/24 vs 01-Jan-2024）。

修正:

• ソースファイルをクリーン。
• または Agent に聞く: 「date_col カラムを DD/MM/YYYY 形式の日付として解析して」。SQL を書いてくれます。

データベース接続

「SSL connection required」

原因: DB が TLS を要求するが、接続文字列がそれを要求していない。

修正: 接続文字列に ?sslmode=require を追加。自己署名証明書には ?sslmode=no-verify。

「Permission denied for relation 」

原因: 接続ロールがテーブルをイントロスペクトできる（information_schema で見える）が SELECT できない。

修正: SELECT を明示的に付与:

GRANT SELECT ON <schema>.<table> TO tablize_reader;

または接続設定でテーブルをイントロスペクションから除外。

大きなテーブルでクエリがタイムアウト

原因: インデックスなしの全表スキャン。

修正:

1. フィルタしているカラムにインデックスを追加。
2. 本番で書き込みが多いテーブルなら、Tablize を読み取りレプリカに向ける。
3. セルフホスト: Tablize ロールの statement_timeout を上げる。

統合

このセクションは内部の統合プレイブックのユーザー向け要約です。既知の特定バグパターンはそこからリンクされています。

データなしで「Sync failed」

可能性の順に原因:

1. トークン期限切れ。 Integrations → サービス → Health を確認。赤インジケータなら OAuth で再接続。
2. 権限がサービス側で取り消し（ユーザーが Tablize アプリを削除、または管理者が取り消し）。
3. ソースによるレート制限。Tablize は自動でバックオフして再試行、同期は最終的に再開。
4. ソース API が変更。修正は数日で出荷。72 時間以上続く場合はサポートへ。

修正: 1 と 2 は、統合ページで Reconnect をクリック。3 は待つ。4 はサポートへ報告。

同期は完了したが行数が違う

原因: カーソルドリフト。ソースが updated_at のセマンティクスを変えたときによく発生（Meta Ads と Amazon は常連）。

修正: 統合の Advanced タブで Backfill from date をクリックし、開始日を選択。Tablize がそのウィンドウを再同期。

チャット内で「Credential not found」

原因: Agent が、ボルトにもう存在しない保存済みシークレットを使おうとした。

修正: Settings → Secrets → 再追加。シークレットは名前を安定参照として使うので、同じ名前で再追加するとすべての参照が復元されます。

初回同期で日付範囲エラー

原因: ソースが start_date > end_date を拒否。ワークスペースのタイムゾーンがソースの想定と異なるときに発生し得ます。

修正: Settings → General でワークスペースタイムゾーンを明示的に設定。それから初回同期を再試行。

Agent とチャット

Agent が「I couldn’t finish that — please try again」を返す

原因: ツール呼び出しがタイムアウトしたか、上流エラー（LLM プロバイダの 5xx）でターンが中断。

修正: 全く同じメッセージを再試行。再失敗するなら小さなステップに分割（「まず X、次に Y」） — 長い多段ターンはタイムアウトしやすい。

Agent が間違った SQL を書き続ける

原因:

• 曖昧なカラム名（2 つのテーブルに status カラムがあり Agent が間違ったほうを選んだ）。
• スキーマラベルが悪い（ドキュメントなしの col1、col2 などのカラム名）。

修正:

• Postgres でカラムコメントを追加 — Agent が読みます:

COMMENT ON COLUMN orders.status IS 'Order status: open|paid|refunded|void';

• またはチャットで明示: 「orders.status を使う、users.status ではない」。

質問の途中で「トークン切れ」

原因: 5 時間ローリングウィンドウが飽和。

修正:

• 待つ（ウィンドウは連続的にロール）。
• トップアップパックを購入 — 即時適用。
• 安定パターンならプランをアップグレード。

課金とトークンを参照。

スケジュール実行

スケジュール Report が出てこない

原因:

1. 支払い失効。 Settings → Billing を確認。
2. パラメータが NULL に評価される。 相対時刻式（last_monday()）は設定済みタイムゾーンが必要。
3. Report のデータブロックでスクリプトエラー — データブロックを手動実行してエラーを見る。

修正: サイドバー → Jobs → スケジュール実行を見つけ → クリックしてステータスとエラーを確認。

期待しているときに Watch が発火しない

原因:

1. 閾値が間違い。 Watch で Test run をクリック — 現在値を表示。
2. デバウンスが長すぎる。 条件が 3 分間 true でデバウンスが 5 分なら発火しません。
3. クワイエットアワー。 スケジュール / クワイエットアワー設定を確認。
4. 承認済みだが未リセット。 前の発火を承認した場合、条件が解決するまで Watch は沈黙。

修正: リストを順に処理。Watch 詳細ページが直近 50 チェック実行を値付きで表示し、通常問題が明らかになります。

Webhook 統合が 0 行で着地

原因: ペイロードの形が、Webhook が期待するよう設定されたものと一致しない。

修正: Ingest → Webhook → Recent deliveries → 任意の配信をクリック → Tablize が何を見たか、なぜパースしなかったかを確認。最も多い: 間違った content-type、または idempotency_key の JSON パスがペイロードに存在しない。

IoT

MQTT メッセージが届かない

原因:

1. ブローカーのホスト / ポートが間違い。
2. TLS 有効だがデバイスが非対応（テストにはプレーンの 1883 を使う）。
3. 認証情報が間違い。

修正: Devices → デバイス → Recent messages。タブが空ならハンドシェイクが失敗 — docker logs emqx（セルフホスト）またはデバイスの MQTT クライアントログを確認。

メッセージは届くが行にならない

原因: JSON パースエラー。

修正: Devices → デバイス → Recent messages が各生ペイロードとパース結果を表示。デバイスが非 JSON フォーマットを話すならデコーダ（Python 関数）をアップロード。

カメラのフレームが更新されない

原因: RTSP ストリームが停止。

修正: Assets → カメラ → Reconnect。Tablize がストリームを再起動。常に不安定なフィードはサンプル間隔を上げる（頻度を下げるほどレジリエント）。

App と Dashboard

公開後 App が空白

原因: Data Contract が dev で動いて prod で失敗するクエリを参照（データ差、スキーマ差、権限）。

修正: App → Logs → 失敗クエリを確認。Agent はほとんどの Data Contract エラーを 1 ターンで修正できます — エラーを説明して修復を依頼。

Dashboard パネルが「No data」

原因:

1. 基底クエリが 0 行を返す — 時間フィルタを確認。
2. 基底テーブルが改名または削除。

修正: パネルで Repair をクリック — Agent が現在のスキーマに基づき修正案を提示。

Notion 埋め込みが何も表示しない

原因: Notion はページの種類によって iframe をブロック。

修正: iframe ではなく oEmbed URL を使用。Notion はすべてのページタイプで oEmbed をレンダリング。

セルフホスト固有

Tablize コンテナから Postgres に接続できない

原因: Docker ネットワーキング — 通常 DATABASE_URL がサービス名ではなく localhost を参照。

修正: postgres://tablize:<pw>@postgres:5432/tablize を使用（サービス名 postgres、localhost ではない）。

MinIO ストレージが埋まる

原因: メディアファイルが必要以上に保持されている。

修正: Settings → Storage → 保持設定（デフォルト: 30 日ソフト削除 + ハード削除）。または MinIO のライフサイクルルールで古いファイルを外部バケットへオフロード。

Tablize コンテナが OOM-killed

原因: ホストの容量不足、またはサンドボックス内の暴走 Python スクリプト。

修正: ホスト RAM を 16 GB に増やし、Python サンドボックスコンテナにメモリ制限を設定:

services:
  python-sandbox:
    deploy:
      resources:
        limits:
          memory: 2G

エスカレーション

上記で解決しなかった？順番に:

1. Agent に聞く — 新しいチャットでエラーを貼る。見たことのない問題でも診断することがあります。
2. コミュニティ Discord を検索 — フッターのリンク。他のユーザーがほとんどのことに遭遇済み。
3. support@tablize.com にメール — ワークスペース ID、やろうとしたこと、エラーテキスト、すでに試したことを含めて。応答時間: Cloud で 1 営業日、Max で 4 時間。
4. Enterprise 顧客の場合: 専用サポートチャネル（Slack またはポータル）を使用。

次のステップ

• 課金とトークン — プランとトークン制限の説明。
• セルフホスト — セルフホスト固有の運用問題。