トラブルシューティング

問題が起きたときは、管理画面、配信API、表示先サイトのどこで止まっているかを分けて確認します。管理画面に保存できていても、公開状態やサイト側のキャッシュによって表示が変わります。

記事が表示されない

1. 正しいワークスペースとAPIを開いているか確認します。
2. エディタが「保存済み」になっているか確認します。
3. 公開状態と公開開始・終了日時を確認します。
4. 配信APIを直接呼び、HTTPステータスを確認します。
5. APIが正しい内容を返すなら、サイト側の取得・キャッシュを調べます。

一覧が空なら、まず記事を1件公開して保存してください。単一取得が404なら、URLのIDはタイトルではなく配信レスポンスのidを使います。

管理画面の場所が変わった

ワークスペースの画面は/w/ワークスペースIDの配下です。配信APIのURLはhttps://api.genko.me/v1/ワークスペースID/エンドポイントです。

ワークスペースのメニューから「設定・プラン」、アバターメニューから「アカウント設定」を開けます。旧URLは新URLへ転送されます。

配信APIがエラーを返す

ローカルでは動くが本番で動かない

ホスティング先にGENKO_API_KEYが登録されているか確認します。.env.localは本番環境へ自動でコピーされません。環境変数を変えた後は、ホスティング先に応じて再起動・再デプロイします。

APIキーをブラウザへ公開することで解決しないでください。取得はサーバー側で行います。APIキーの管理を参照してください。

型が古い・追加したAPIが見つからない

npx @genko-me/cli pull

実行して型とAPI一覧を更新します。現行CLIのクライアントはschema.tsのapisを参照するため、API追加時の手動編集は不要です。同期対象を限定している場合はpull --select-apisで選択に追加してください。古いコードでAPIを列挙している場合は現行のクライアント設定へ合わせてください。pullはクライアントを上書きしません。

fieldsで返す項目を減らしている場合は、型があってもその項目は実際には返りません。参照フィールドがunknownになるのは生成型の仕様です。クエリを確認してください。

保存したのにサイトが古い

公開中の記事の更新が配信APIには反映されているなら、サイト側のキャッシュや静的生成を確認します。Webhookが成功していても、受信後の処理が正しいページを更新しているとは限りません。

Webhookで、通知と再検証・再ビルドの両方を確認してください。予約公開も同じで、APIの時刻判定とサイトの画面更新は別です。

プレビューが動かない

保存済みで、テンプレートに{id}と{key}があることを確認します。SDKのViewにはページで受け取ったsearchParamsを渡してください。独自の取得処理を使う場合はdraftKeyを取得メソッドへ渡します。キーを再生成した場合は古いURLが使えません。

親記事が表示されても、下書きの参照先は展開されません。下書きプレビューを参照してください。

List・Viewが何も表示しない

List / Viewの子要素に<ListItem id="title" /> / <ViewItem id="title" />のように表示したいフィールドIDを指定します。状態を調べるときは親の直下に<Error template />と<Null template />を配置してください。状態部品を省略すると、エラーや空データでも何も表示しません。

フィールドIDと生成スキーマのfieldsを確認します。titleとnameは別のIDです。@/lib/clientが見つからない場合は、importエイリアスと生成先の設定を合わせます。

ページ送りだけ失敗する

ページを再読み込みして確認します。ページ送りの署名は1時間で期限切れになり、APIキーの交換後も再読み込みが必要です。

サーバー環境のGENKO_API_KEYとクライアントに設定したキーが一致するか、カスタムfetch / wrapRequestを追加していないかを確認します。Next.js 16以降のApp Router・Node.jsランタイムで実行し、静的エクスポートは使わないでください。ページ送りの仕様も参照してください。

メディアを削除できない・画像が変わらない

メディアを選び、詳細パネルで使用しているコンテンツを確認します。使用中のファイルは、参照先の記事から外して保存してから削除します。「削除予定」は一度も添付されていないファイルです。

差し替え後は配信APIから新しいURLを取得します。変換が効かない場合は、元画像のサイズ・アニメーション・25MBの変換上限も確認してください。メディア管理と画像変換を参照してください。

チームへ招待できない

ワークスペースの「設定・プラン」→「メンバー」で、オーナー権限、チーム自身のプラン、保留中の招待を確認します。未承諾の有効な招待も人数枠を使います。個人の有料プランの共有枠にいる無料チームでも、人数は3名までです。

招待メールが複数ある場合は最新のものを使い、招待先と同じメールアドレスで参加します。チームとメンバーを参照してください。

Webhookが届かない

対象APIの「設定」からWebhookの操作メニューで「配信ログ」を開き、エラーと送信先の応答を確認します。自動再送はありません。受信先を修正したら対象のログで「もう一度送る」を押します。「テスト送信」は過去のイベントを再送する操作ではありません。詳しくはWebhookを参照してください。

届いても署名の検証に失敗する場合は、x-genko-timestampとx-genko-signatureの両方を使い、JSONへ変換する前の生の本文を検証しているか確認します。署名はtimestamp.本文のHMAC-SHA256で、現在時刻との差が300秒を超えると拒否されます。タイムスタンプなしの旧方式は使えません。SDKは0.6.0以降で検証できます。

問い合わせる

解決しない場合は、次の情報を添えて[email protected]へ連絡してください。

• 何をしようとして、どの操作で止まったか。
• 発生日時とタイムゾーン。
• ワークスペース・API、エラーのステータスとメッセージ。
• ローカル／本番のどちらか、再現する頻度。

APIキー、パスワード、確認コード、プレビューキーを含むURLは送らないでください。