つまずきやすいポイント

このページの使い方

flowchart LR
    A["エラーや症状"] --> B["下の索引で<br/>場面と症状を探す"]
    B --> C["公式ドキュメントの記述を読む"]
    C --> D["AIに質問する<br/>（公式ページのURL付き）"]
    D --> E["AIの回答を<br/>公式ページで確かめる"]

• このページには、公式ドキュメントに書かれている対処だけを載せています。公式ドキュメントに記載がない症状は載せていません。
• 見出しの英語のメッセージは、画面やログに表示されるとおりに書いています。表示されたメッセージの一部で、このページをページ内検索できます。
• 見つからない場合は、ページ末尾の「どれにも当てはまらないとき」の依頼文を使います。

AIへの質問の基本形

各項目の「AIへの質問」は、次の基本形の【】の部分を埋めたものです。

症状の索引

サイトを作る・起動する

依存パッケージのインストールに失敗する

• 場面：npm create emdash@latest でサイトの雛形を作ったとき
• 公式ドキュメントの記述：インストールに失敗しても、プロジェクトのファイルは残ります。作成ツールが表示する再試行のコマンドを実行してから先に進みます（公式「はじめてのEmDashサイト作成」）。pnpmで作った場合は、プロジェクトのディレクトリに移動して pnpm install を実行します（公式「ブログを作る」）。
• 対応する公式ページ：はじめてのEmDashサイト作成（サイトの雛形を作る）、ブログを作る（ブログの雛形を作る）
• AIへの質問：基本形の【公式ページ】に「Create your first EmDash site」（https://docs.emdashcms.com/getting-started/）、【見出し】に「Scaffold the site」を入れ、作成ツールが表示したメッセージを貼ります。

管理画面（/_emdash/admin）が404になる

• 場面：Astroの国際化（i18n）を設定したあと
• 公式ドキュメントの記述：既定のロケールにプレフィックスを付けるAstroのルーティング設定（routing: { prefixDefaultLocale: true } や routing: "prefix-always"）は、EmDashの管理画面を壊します。/_emdash/admin と、そのセットアップ・ログイン・コンテンツの各ページが 404 を返します。Astroの既定のルーティング（prefix-other-locales）を使います。公開URLに既定のロケールを含める必要がある場合は、prefixDefaultLocale を有効にせず、サイトの前段でリダイレクトかリライトを設定します。
• 対応する公式ページ：国際化（i18n）
• AIへの質問：基本形の【公式ページ】に「Internationalization (i18n)」（https://docs.emdashcms.com/guides/internationalization/）、【見出し】に「Do not prefix the default locale」を入れ、astro.config.mjs の i18n の設定部分を貼ります。

SQLiteのデータが消える

• 場面：Node.jsのサイトをSQLiteで動かしているとき
• 公式ドキュメントの記述：SQLiteには、データが残り続けるファイルシステムが必要です。一時的なストレージしかない環境では、追加の設定なしには動きません。
• 対応する公式ページ：データベースの選択（SQLite）
• AIへの質問：基本形の【公式ページ】に「Choose a database」（https://docs.emdashcms.com/deployment/database/）、【見出し】に「SQLite」を入れ、サイトを動かしている環境の名前を書きます。

管理画面にログインする

「No passkeys registered」と表示される

• 場面：パスキーでログインしようとしたとき
• 公式ドキュメントの記述：パスワードマネージャーからパスキーが削除された可能性があります。管理者に、復旧用のマジックリンクを送ってもらいます。サイトにメールの設定が必要です。
• 対応する公式ページ：認証（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Authentication」（https://docs.emdashcms.com/guides/authentication/）、【見出し】に「Troubleshooting」を入れます。

「Passkey authentication failed」と表示される

• 場面：パスキーでログインしようとしたとき。特に、ローカルで使っていたパスキーでデプロイ先にログインしようとしたとき
• 公式ドキュメントの記述：多くの場合、パスキーが別のドメイン用に作られています。パスキーはドメインに結び付いています。localhost:4321 用のパスキーは example.com では使えません。ドメインごとに新しいパスキーを登録します。
• 対応する公式ページ：認証（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Authentication」（https://docs.emdashcms.com/guides/authentication/）、【見出し】に「Troubleshooting」を入れ、ログインしようとしたURLのドメイン部分を書きます。

登録したパスキーをすべて失った

• 公式ドキュメントの記述：ほかの管理者に復旧用のマジックリンクを送ってもらいます（サイトにメールの設定が必要）。リンクは15分以内に使ってログインし、アカウント設定で新しいパスキーを登録します。自分が唯一の管理者で、メールも設定していない場合は、データベースからサイトの認証をリセットする必要があります。
• 対応する公式ページ：認証（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Authentication」（https://docs.emdashcms.com/guides/authentication/）、【見出し】に「Lost all passkeys」を入れ、ほかに管理者がいるか、メールを設定しているかを書きます。

「Account is not in the allowlist」と表示される（Atmosphereログイン）

• 公式ドキュメントの記述：ログインに使ったハンドルかDIDが、allowedDIDs／allowedHandles に含まれていません。ワイルドカードのパターンが *. で始まっているかを確認します。ハンドルの照合はDNS／HTTPで検証されるため、ハンドルのDIDの記録が、プロバイダーが返したDIDと現在一致していない場合は拒否されます。
• 対応する公式ページ：Atmosphereログイン（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Atmosphere Login」（https://docs.emdashcms.com/guides/atmosphere-auth/）、【見出し】に「Troubleshooting」を入れ、allowedDIDs／allowedHandles の設定部分を貼ります。

「Self-signup is not allowed」と表示される（Atmosphereログイン）

• 公式ドキュメントの記述：コールバックまでは届いていますが、許可リストが設定されておらず、最初のユーザーでもありません。アカウントのDIDを allowedDIDs に、または検証済みのハンドルを allowedHandles に追加します。メールでの招待は、AtmosphereのDIDをEmDashのユーザーに結び付けません。
• 対応する公式ページ：Atmosphereログイン（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Atmosphere Login」（https://docs.emdashcms.com/guides/atmosphere-auth/）、【見出し】に「Troubleshooting」を入れます。

ログインしても、エラーなしでログイン画面に戻る（Atmosphereログイン）

• 場面：ローカル開発中
• 公式ドキュメントの記述：ほとんどの場合、ループバックのCookieの問題です。Astroの server.host を "127.0.0.1" に設定したうえで、http://127.0.0.1:4321 で管理画面を開いてやり直します。
• 対応する公式ページ：Atmosphereログイン（ローカル開発／トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Atmosphere Login」（https://docs.emdashcms.com/guides/atmosphere-auth/）、【見出し】に「Local development」を入れ、管理画面を開いているURLを書きます。

自前のドメインのハンドルを解決できない（Atmosphereログイン）

• 公式ドキュメントの記述：自前のドメインのハンドルには、did=<your-did> を含む _atproto.<handle> のDNS TXTレコードか、DIDを含む https://<handle>/.well-known/atproto-did のファイルの、少なくとも一方が必要です。allowedDIDs に書いたDIDは直接照合されるため、この影響を受けません。
• 対応する公式ページ：Atmosphereログイン（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Atmosphere Login」（https://docs.emdashcms.com/guides/atmosphere-auth/）、【見出し】に「Troubleshooting」を入れます。

「No Access JWT present」と表示される（Cloudflare Access）

• 公式ドキュメントの記述：リクエストがAccessのJWTなしでEmDashに届いています。Accessがアプリケーションを保護していないか、Accessのポリシーが管理画面のルートに一致していません。Accessのアプリケーションが /_emdash/* のパス全体を対象にしているか、ポリシーにそのユーザーが含まれているかを確認します。
• 対応する公式ページ：認証（Cloudflare Access／トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Authentication」（https://docs.emdashcms.com/guides/authentication/）、【見出し】に「Cloudflare Access」の「Troubleshooting」を入れ、Accessのアプリケーションに設定したパスを書きます。

「JWT audience mismatch」と表示される（Cloudflare Access）

• 公式ドキュメントの記述：設定の audience がJWTと一致していません。Accessのアプリケーション設定にある Application Audience（AUD）Tag を確認します。
• 対応する公式ページ：認証（Cloudflare Access／トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Authentication」（https://docs.emdashcms.com/guides/authentication/）、【見出し】に「Cloudflare Access」の「Troubleshooting」を入れます。AUD Tagの値そのものは貼りません。

記事を公開する

公開したはずの記事がサイトに表示されない

• 公式ドキュメントの記述：エディターの状態表示が「公開済み」になっているかを確認します。「下書き」や「予約済み」では表示されません。
• 対応する公式ページ：ブログを作る（最初の投稿を公開する）
• AIへの質問：基本形の【公式ページ】に「Create a Blog」（https://docs.emdashcms.com/guides/create-a-blog/）、【見出し】に「Publish the first post」を入れ、エディターに表示されている状態を書きます。

ローカルで書いた記事が、デプロイ先にない

• 公式ドキュメントの記述：ローカル開発中に作った投稿は、ローカルの開発用データベースにだけ保存されます。サイトをデプロイしても、本番にはコピーされません。
• 対応する公式ページ：ブログを作る（最初の投稿を公開する）
• AIへの質問：基本形の【公式ページ】に「Create a Blog」（https://docs.emdashcms.com/guides/create-a-blog/）、【見出し】に「Publish the first post」を入れます。

Cloudflareにデプロイする

「D1 binding not found」と表示される

• 公式ドキュメントの記述：wrangler.jsonc のバインディング名が、データベースの設定と一致しているかを確認します。d1({ binding: "DB" }) と "binding": "DB" のように、名前をそろえます。
• 対応する公式ページ：Cloudflareへのデプロイ（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Deploy to Cloudflare」（https://docs.emdashcms.com/deployment/cloudflare/）、【見出し】に「Troubleshooting」を入れ、wrangler.jsonc の d1_databases と、astro.config.mjs の database の設定部分を貼ります。

「R2 binding not found」と表示される

• 公式ドキュメントの記述：R2バケットが正しくバインドされているかを確認します。r2({ binding: "MEDIA" }) と "binding": "MEDIA" のように、名前をそろえます。
• 対応する公式ページ：Cloudflareへのデプロイ（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Deploy to Cloudflare」（https://docs.emdashcms.com/deployment/cloudflare/）、【見出し】に「Troubleshooting」を入れ、wrangler.jsonc の r2_buckets と、astro.config.mjs の storage の設定部分を貼ります。

スキーマのエラーが出る

• 公式ドキュメントの記述：Workerのログを wrangler tail で表示しながらエラーを再現し、元のメッセージを記録します。そのうえで、その出力を添えてissueを登録します。
• 対応する公式ページ：Cloudflareへのデプロイ（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Deploy to Cloudflare」（https://docs.emdashcms.com/deployment/cloudflare/）、【見出し】に「Migration errors」を入れ、wrangler tail の出力を貼ります。

画像が縮小されずに元のサイズで表示される／画像のリクエストが500になる

• 公式ドキュメントの記述：IMAGES バインディングがない場合の症状です。内部のメディアのルートでは、元のファイルがそのまま返され、ログにも何も出ません。バケットのURLから配信している場合は、リクエストが500で失敗します。imageService: "passthrough" を指定すると、変換を使わない構成にできます。デプロイで実際に使われる設定は、wrangler.jsonc ではなく、ビルドで生成される設定ファイル（既定では dist/server/wrangler.json）で確認します。
• 対応する公式ページ：Cloudflareへのデプロイ（画像の変換）
• AIへの質問：基本形の【公式ページ】に「Deploy to Cloudflare」（https://docs.emdashcms.com/deployment/cloudflare/）、【見出し】に「Image transformation」を入れ、画像のURLが /_emdash/api/media/file/ で始まるか、バケットのURLかを書きます。

新しい画像のリクエストが 9422 のエラーで失敗する

• 公式ドキュメントの記述：Images Freeプランは、月あたり5,000件の一意な変換までです。上限を超えると、キャッシュ済みの変換は引き続き配信されますが、新しい変換は 9422 のエラーを返し、画像のリクエストは失敗します。
• 対応する公式ページ：Cloudflareへのデプロイ（画像の変換）
• AIへの質問：基本形の【公式ページ】に「Deploy to Cloudflare」（https://docs.emdashcms.com/deployment/cloudflare/）、【見出し】に「Image transformation」を入れます。料金の確認先として、Cloudflare公式の料金ページ（https://developers.cloudflare.com/images/pricing/）も指定します。

「Email is not configured」と表示される

• 場面：本番のWorkerで、マジックリンクのログイン、チームへの招待、コメントの通知を使ったとき
• 公式ドキュメントの記述：本番のWorkersには、既定のメール配信サービスがありません。メールのプラグインを有効にするまで、この表示になります。Cloudflareのメールプラグインは send_email バインディングを使い、送信元ドメインをCloudflare Email Sendingで登録・検証しておく必要があります。
• 対応する公式ページ：Cloudflareへのデプロイ（メール）
• AIへの質問：基本形の【公式ページ】に「Deploy to Cloudflare」（https://docs.emdashcms.com/deployment/cloudflare/）、【見出し】に「Email」を入れます。

データベースを更新する（コアマイグレーション）

いずれも、公式「コアDBマイグレーション」のトラブルシューティングに書かれている項目です。

• 対応する公式ページ：コアDBマイグレーション（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Manage core database migrations」（https://docs.emdashcms.com/deployment/core-migrations/）、【見出し】に「Troubleshooting」を入れ、実行したコマンドと表示されたメッセージを貼ります。

EmDashを更新する

更新後にサイトが壊れた

• 公式ドキュメントの記述：
  • ビルドが失敗する、または自分で作ったページが実行時にエラーになる場合：飛ばしたバージョンのリリース項目のうち、Breaking と書かれたものを読み、書かれている変更をします。
  • プラグインが読み込まれない場合：そのプラグイン自身のリリース項目と、公式「サイトのプラグイン更新」を読みます。
  • エラーがAstroのAPIや @astrojs/* のパッケージを名指ししている場合：EmDashにはAstro 6以降が必要です。Astroのアップグレードガイドに、astro と公式インテグレーションをまとめて更新する方法が書かれています。
  • 前のリリースに戻す場合：対応する前のバージョンのパッケージを入れ直し、その成果物をデプロイし直します。入れ直してもコアマイグレーションは元に戻りません。前の成果物がマイグレーション後のデータベースを使えない場合は、アクセスを止め、更新前のデータベースと成果物をまとめて復元します。メディアは、更新で変わった場合だけ復元します。
• 対応する公式ページ：EmDashのアップデート（更新後にサイトが壊れた場合）、サイトのプラグイン更新
• AIへの質問：基本形の【公式ページ】に「Update EmDash」（https://docs.emdashcms.com/deployment/updating/）、【見出し】に「If the site breaks after an update」を入れ、更新前と更新後の emdash のバージョンと、表示されたエラーを貼ります。

サンドボックス型プラグインを動かす

見出しは、サーバーのログに出るメッセージ、または管理画面が返すエラーコードです。

[emdash] Sandboxed plugins are disabled because wrangler.jsonc has no LOADER Worker Loader binding

• 公式ドキュメントの記述：ビルド時のWranglerの設定に、LOADER という名前の worker_loaders バインディングがないため、Cloudflareのアダプターがサンドボックスランナーを選択しませんでした。Workersの無料プランでは想定どおりの状態です。Workersの有料プランでは、wrangler.jsonc でバインディングを有効にしてサイトをビルドし直します。
• 対応する公式ページ：プラグインサンドボックス（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Configure the plugin sandbox」（https://docs.emdashcms.com/deployment/plugin-sandbox/）、【見出し】に「Troubleshooting」を入れ、Workersのプランが無料か有料かを書きます。

Plugin sandbox is configured but not available on this platform

• 公式ドキュメントの記述：コロンのあとの文が原因を示します。
  • the worker has no worker_loaders binding named LOADER：wrangler.jsonc に LOADER という名前の worker_loaders バインディングが必要です。デプロイにはWorkersの有料プランが必要です。
  • the worker entrypoint does not export PluginBridge：main が指すファイルから PluginBridge をエクスポートする必要があります。
  • workerd is missing or its binary does not run on this platform（Node.js）：./node_modules/.bin/workerd --version（Windowsでは node_modules\\.bin\\workerd.cmd --version）を実行します。失敗する場合は、動かす環境で、オプションの依存パッケージを有効にしてインストールし直します。
• 対応する公式ページ：プラグインサンドボックス（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Configure the plugin sandbox」（https://docs.emdashcms.com/deployment/plugin-sandbox/）、【見出し】に「Troubleshooting」を入れ、メッセージ全体（コロンのあとまで）を貼ります。

workerd failed to start within 10 seconds

• 公式ドキュメントの記述：子プロセスは起動しましたが、プラグインのサービスが10秒以内に応答しませんでした。このメッセージより前の [emdash:workerd] で始まる行に、workerd 自身の出力（設定や起動時のエラー）があります。ランナーは次の呼び出しで再試行します。
• 対応する公式ページ：プラグインサンドボックス（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Configure the plugin sandbox」（https://docs.emdashcms.com/deployment/plugin-sandbox/）、【見出し】に「Troubleshooting」を入れ、[emdash:workerd] で始まる行も含めて貼ります。

workerd crashed 5 times in 60 seconds, giving up

• 公式ドキュメントの記述：ランナーは workerd の再起動をやめています。このメッセージより前の [emdash:workerd] workerd exited with <reason> の行が、それぞれの終了コードかシグナルを示します。原因を直してからサーバーを再起動します。
• 対応する公式ページ：プラグインサンドボックス（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Configure the plugin sandbox」（https://docs.emdashcms.com/deployment/plugin-sandbox/）、【見出し】に「Troubleshooting」を入れ、workerd exited with の行を貼ります。

プラグインのインストールで SANDBOX_NOT_AVAILABLE が返る

• 公式ドキュメントの記述：ランナーがないか使えないため、管理画面からのインストールが拒否されました。ランナーを設定している場合、エラーメッセージの末尾に、起動時の警告と同じ原因が書かれています。環境に合わせてランナーを設定するか原因を直し、デプロイし直します。
• 対応する公式ページ：プラグインサンドボックス（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Configure the plugin sandbox」（https://docs.emdashcms.com/deployment/plugin-sandbox/）、【見出し】に「Troubleshooting」を入れ、エラーメッセージ全体を貼ります。

Plugin <id> exceeded wall-time limit of 30000ms と表示される

• 公式ドキュメントの記述：フックかルートが、実行時間の上限（30秒）を超えました。フックの場合、EmDashは EmDash: Sandboxed plugin <id> で始まるログを出し、そのプラグインの結果なしでリクエストを続けます。プラグインのルートの場合は、呼び出し元に失敗が返ります。上限は固定で、emdash() の設定では変えられません。
• 対応する公式ページ：プラグインサンドボックス（リソースの上限）
• AIへの質問：基本形の【公式ページ】に「Configure the plugin sandbox」（https://docs.emdashcms.com/deployment/plugin-sandbox/）、【見出し】に「Resource limits」を入れます。

WordPressから移行する

XMLファイルを解析できない

• 公式ドキュメントの記述：WordPressの「ツール → エクスポート」からもう一度書き出し、ダウンロードが完了したかを確認します。文字コードを変えるツールでXMLを編集しないでください。
• 対応する公式ページ：WordPressからの移行（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Migrate from WordPress」（https://docs.emdashcms.com/migration/from-wordpress/）、【見出し】に「Troubleshooting」を入れます。XMLファイルの中身は貼りません。

コレクションや投稿タイプが「非互換」と表示される

• 公式ドキュメントの記述：既存のフィールドに、同じスラッグで型の違うものがあります。確認画面で投稿タイプを展開して、衝突しているフィールドを見つけます。投稿タイプの取り込み先を変えるか、「コンテンツタイプ」でフィールドを調整してからやり直します。準備の段階では足りないフィールドが追加されますが、既存のフィールドの型は変わりません。
• 対応する公式ページ：WordPressからの移行（トラブルシューティング）、コンテンツのインポート（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Migrate from WordPress」（https://docs.emdashcms.com/migration/from-wordpress/）、【見出し】に「Troubleshooting」を入れ、衝突しているフィールドの名前と型を書き写します。

メディアのダウンロードに失敗する

• 公式ドキュメントの記述：元の添付ファイルに、WordPressにログインしていない状態でアクセスできるかを確認します。認証が必要なメディア、削除されたファイル、プライベートネットワークのアドレスへのリダイレクトは、個別に失敗してメディアのエラー一覧に残ります。アクセスできるように直してからメディアの手順をやり直すと、完了済みの同じ内容のファイルは再利用されます。
• 対応する公式ページ：WordPressからの移行（トラブルシューティング）、コンテンツのインポート（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Migrate from WordPress」（https://docs.emdashcms.com/migration/from-wordpress/）、【見出し】に「Troubleshooting」を入れ、「メディアエラー」に表示されたURLを1つ書きます。

サイトは検出されたが、直接インポートできない

• 公式ドキュメントの記述：wordpress-rest の結果は調査だけです。WXRファイルをアップロードするか、EmDash Exporterをインストールしてもう一度調べます。
• 対応する公式ページ：コンテンツのインポート（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Content import」（https://docs.emdashcms.com/migration/content-import/）、【見出し】に「Troubleshooting」を入れます。

インポートが途中で止まった

• 公式ドキュメントの記述：管理画面のインポートは既存のエントリーを飛ばすように作られていますが、照合はWordPressのIDではなく、コレクション・スラッグ・ロケールで行います。やり直しの間にスラッグが変わった場合は、両方のエントリーを確認して重複を手作業で解消します。中断したあとは、WordPressのサイトを削除したりリダイレクトしたりしないでください。先にコレクションの件数を比べ、エラーを確認し、メディアのダウンロードを終え、書き換えたリンクを確認します。
• 対応する公式ページ：WordPressからの移行（途中まで進んだインポートのやり直し）
• AIへの質問：基本形の【公式ページ】に「Migrate from WordPress」（https://docs.emdashcms.com/migration/from-wordpress/）、【見出し】に「Retry a partial import」を入れ、インポートの方法（WXR／Exporter）を書きます。

プラグインを公開する

MANIFEST_PUBLISHER_MISMATCH で公開に失敗する

• 公式ドキュメントの記述：有効なセッションが、マニフェストで固定した publisher とは別のAtmosphereアカウントです。emdash-plugin switch <did> で固定したアカウントに切り替えるか、プラグインを本当に別のアカウントに移す場合はマニフェストの publisher を更新します。
• 対応する公式ページ：バンドルと公開（公開者の不一致）、マニフェスト（公開者の固定）
• AIへの質問：基本形の【公式ページ】に「Bundling and publishing」（https://docs.emdashcms.com/plugins/creating-plugins/publishing/）、【見出し】に「Publisher mismatch」を入れ、emdash-plugin whoami の結果を貼ります。

自動リリースのエラー

いずれも、公式「自動リリース」のトラブルシューティングに書かれている項目です。

• 対応する公式ページ：自動リリース（トラブルシューティング）
• AIへの質問：基本形の【公式ページ】に「Automated plugin releases」（https://docs.emdashcms.com/plugins/creating-plugins/delegated-releases/）、【見出し】に「Troubleshooting」を入れ、GitHub Actionsのログのエラー部分を貼ります。

どれにも当てはまらないとき