トラブルシューティング
よくある症状の原因と直し方です。エラー文で探すときは、ページの中を検索してください。
このページの内容
this application wants mode: 'server'
原因
staticモードで、リクエストが要るものを使っています。エラーの1行目は拒んだものの種類を示し、その下の行がファイルを挙げます。
直し方
それが必要なら、framework()のmodeを'server'に変えます。paths、site、cspはstaticモードだけのオプションなので外します。CSPはguard.tsでnonce()を使ってヘッダーに書きます。型だけを使っているなら、import typeに書き換えます。staticモードのままで通ります。要らないなら、そのコードを消します。検索や絞り込みのようなGETのフォームなら、Server Actionは要りません。
static build needs pathnames for …
原因
staticモードで、パラメータを持つルートに当てはまるURLがpathsに1つもありません。ビルドはパラメータの値を自分では決められません。
直し方
framework()のpathsで、そのルートのURLを並べます。
the "paths" option supplied pathnames no route wants
原因
staticモードで、pathsが返したURLのどれかがどのルートにも当たりません。多くはURLの打ち間違いです。
直し方
エラーの後ろに並んだURLを直すか、pathsから外します。
the "paths" option supplied pathnames that still hold a parameter, …
原因
staticモードで、pathsが返したパスに:slugのようなパラメータが残っています。locales.pathsでロケールだけを展開したときによく起きます。パラメータを残したパスを受け取れるのは、横にfallback.tsxのあるページだけです。
直し方
残ったパラメータも、pathsの中で値に展開します。ビルドしていない値に答えたいページなら、横にfallback.tsxを置きます。route.tsとredirect.tsには置けません。
… shell locations whose parameter names are not their pattern's
原因
シェルの場所のパラメータの名前が、パターンと違います。/:locale/posts/:idに/en/posts/:slugを返すと、このエラーになります。
直し方
括弧の中のパターンと同じ名前で書きます。
static build needs shell locations for …
原因
fallback.tsxより上のレイアウトが受け取るパラメータを、シェルの場所が埋めていません。レイアウトはシェルでもHTMLとして書くので、その値が要ります。:localeを残した場所を返したときは、… leave out a parameter a layout above their fallback.tsx receivesのエラーになります。
直し方
/ja/posts/:idのように、レイアウトが受け取るパラメータを埋めた場所を返します。locales.pathsの結果を残せば、ロケールごとの場所になります。
… with a segment named !fallback
原因
!fallbackは、ビルドがシェルを書くディレクトリの名前です。pathsの返すパスには使えません。%21fallbackのようにエスケープしても同じです。
直し方
その値の名前を変えるか、pathsから外します。
the shell for … would also answer …
原因
シェルの書き換えのルールが、ルート表で先に試されるルートのURLにも当たります。ホスティングでは、そのURLにもシェルが返ってしまいます。
直し方
先のルートがページなら、そこにもfallback.tsxを置きます。重なるURLが1つだけなら、そのURLをpathsに並べます。どちらでもなければ、そのルートに当たらないシェルの場所を返します。
… shell locations a params schema refused
原因
シェルの場所に埋めた値を、レイアウトのparamsSchemaが拒みました。/fr/posts/:idのように、ロケールの集合に無い値でよく起きます。
直し方
その場所をpathsから外すか、値を直します。
the shell for … called notFound() while it rendered
原因
ビルドがシェルを描く間に、レイアウトかfallback.tsxのServer ComponentがnotFound()を呼びました。シェルには値が無いので、データにあるかどうかは決められません。
直し方
notFound()は、ブラウザで値を読むClient Componentから呼びます。
the shell for … was answered by …
原因
シェルのURL（/posts/!fallback）に、別のルートが答えました。!fallbackを値として受け取ったページか、ルート表で先に試される、同じ位置に別の名前のパラメータを持つfallback.tsxのページです。
直し方
そのルートに当たらないシェルの場所を返します。
static build could not render …
原因
staticモードのビルドで、そのページの描画中にServer Componentがエラーになりました。上にSuspenseの境界が無いClient Componentがエラーになったときも、同じエラー文が出ます。
直し方
元のエラーは、このエラー文より上にページのURLと一緒に出力されています。それを手がかりに直します。
vite devでだけ表示できるページ
原因
staticモードでも、vite devはファイルを書かずにリクエストのたびにページを描画します。pathsに無い値も、fallback.tsxが無ければページで描画します。Server Componentがエラーになっても、500を返して動き続けます。
直し方
公開する前にvite buildを通し、エラーが出たらその文に従って直します。書き出したサイトはvite previewで確かめます。ホスティングと同じように、dist/client/のファイルだけを返します。
200で返る404.html
原因
staticモードでは、404.htmlに付くステータスをホスティングが決めます。ビルドが書けるのはページまでで、応答のステータスは書けません。
直し方
ホスティングの設定で、存在しないURLに404.htmlを404のステータスで返すようにします。
GitHub Pagesで404になるビルドしていない値
原因
GitHub Pagesには書き換えのルールがありません。_redirectsを読まないので、ファイルの無いURLには404.htmlを返します。
直し方
書き換えのできるホスティングに移すか、値をすべてpathsに並べます。
Cloudflareで書き出したページにシェルが返る
原因
Cloudflareが読む_redirectsのルールは、固定のURLが2,000個までです。超えた分は読まれず、書き出したページにもシェルのルールが当たります。ビルドは_redirects has … rules Cloudflare counts as staticの警告を出します。パラメータを含むルールは100個までで、超えると… counts as dynamicの警告になります。
直し方
シェルのあるパターンの下で書き出す値を減らし、残りはシェルに任せます。ファイルを先に返すNetlifyでは、書き出したページにシェルが返ることはありません。
Cloudflareでリダイレクトがループする
原因
Workersの静的アセットで、html_handlingがdrop-trailing-slashになっています。シェルのルールはスラッシュで終わるURLへ書き換えるので、スラッシュを外すリダイレクトとの間でループします。noneでは、シェルが404になります。
直し方
html_handlingを既定のauto-trailing-slashかforce-trailing-slashにします。
_redirects cannot list …
原因
書き出した値に、:bのような:と英字の並びか*が入っています。ホスティングはそれをパラメータとして読むので、そのURLにファイルを返すルールを書けません。Cloudflareでは、そのURLにシェルが返ります。
直し方
URLに:や*が入らない値にします。
public/_redirects line … before its shell's rule
原因
public/_redirectsのルールが、シェルのルールより先にシェルの場所に当たります。/* /index.html 200のようなルールです。
直し方
そのルールを外すか、シェルの場所に当たらないように狭めます。
this build runs on Vercel, which does not read _redirects
原因
Vercelの上のビルドがシェルを書きましたが、vercel()がありません。Vercelは_redirectsを読まないので、どのURLにもシェルは返りません。
直し方
@k8ordo/framework/vercelのvercel()をframework()の隣に足します。
… has "!fallback" in its HTML
原因
レイアウトは、pathnameとしてシェルのURL（/posts/!fallback）を受け取ります。それをリンクやcanonicalに書くと、訪問者のURLと違うものがHTMLに残ります。
直し方
URLから作るものは、ブラウザでusePathname()を読むClient Componentで描きます。
the "csp" option cannot go into a page's <meta> as it is
原因
staticモードのcspオプションに、<meta>では効かないディレクティブか'strict-dynamic'などが入っています。<meta>で効かないのはframe-ancestors、report-uri、sandboxの3つです。1つのエントリに複数のソースを空白区切りで書いた場合も、同じエラーになります。
直し方
<meta>で効かないディレクティブは、ホスティングのヘッダーで設定します。'strict-dynamic'は外します。フレームワークのモジュールのスクリプトは、'self'で許可されます。ソースは1つずつ配列の要素にします。
403になるServer Actionの送信
原因
serverモードで、ハンドラが受け付けるPOSTは、OriginヘッダーのホストがリクエストのURLのホストと一致するものだけです。前に置いたプロキシがHostを書き換えていると、この2つが一致しません。
直し方
プロキシで、元のHostをそのまま渡します。ハンドラを自分で呼ぶ場合は、訪問者がアクセスしたURLでRequestを作ります。
redirect()のあとも移らないページ
原因
serverモードで、redirect()は例外を使って処理を終えます。tryの中で呼ぶと、catchがその例外を受け取ります。
直し方
redirect()はtryの外で呼びます。
… belongs to what answers the request, and a page is a render
原因
serverモードで、ページの描画の中からcookies()やresponseHeaders()、requestHeaders()を呼んでいます。これらはリクエストに応答する処理のためのAPIで、ページの描画からは呼べません。
直し方
リクエストのヘッダーやCookieを読むなら、ページが受け取るrequestを使います。書くなら、guard.tsかServer Actionに移します。
internal errorとだけ表示されるページ
原因
serverモードで、ハンドラが応答を作れず、serve()が500を返しています。上にSuspenseの境界が無い場所でServer Componentがエラーになると、こうなります。
直し方
エラーの内容は、サーバーのログにk8ordo: GET /products/1 failedのような行で出ています。訪問者に自前のエラー画面を見せるなら、error.tsxを置きます。
HTTPで保存されないCookie
原因
serverモードのcookies().set()では、secureの既定がtrueです。ブラウザは、HTTPSでないHTTPで受け取ったSecureのCookieを保存しません。既定がfalseになるのは、HTTPでlocalhostか127.0.0.1、[::1]に来たリクエストだけです。
直し方
本番はHTTPSで配信します。それ以外の場所をHTTPで動かすなら、setにsecure: falseを渡します。
a cookie with sameSite "none" has to be secure
原因
serverモードで、sameSite: 'none'のCookieにsecure: falseを渡しています。ブラウザはSecureの無いSameSite=Noneを捨てるので、cookies().set()がその場でエラーにします。
直し方
sameSite: 'none'のCookieはsecureのままにして、HTTPSで配信します。
本番でだけ出るハイドレーションのエラー
原因
ルートレイアウトが描画した文書は、まるごとハイドレーションの対象です。CDNの機能でHTMLが書き換えられると、Reactが描画する内容とHTMLが食い違います。Webフォントの埋め込み、メールアドレスの難読化、スクリプトの遅延読み込みがその例です。
直し方
CDNのその機能を切ります。フォントやスクリプトをサイトと同じオリジンから配信すると、CDNが書き換えるものが無くなります。
型の付かないhref()とparams
原因
tsconfig.jsonのincludeに.k8ordo/が含まれていません。.k8ordoはドットで始まるので、".k8ordo"とディレクトリ名だけを書いても読み込まれません。型はclone直後と同じになります。
直し方
includeに.k8ordo/**/*.tsのようにグロブで書きます。
clone直後のPagePropsの型
原因
.k8ordo/は生成物でgitに入らないので、cloneした直後にはまだありません。ルート表が無いあいだ、PagePropsのparamsは文字列の型になります。mode: 'server'ではrequestとsearchも型から消え、Property 'request' does not existのエラーになります。
直し方
tscの前にvite devかvite buildを一度実行して、.k8ordo/を生成します。
routes/ holds only page.tsx, …
原因
routes/の中に、page.tsxやlayout.tsxのようなルートのファイルでないものがあります。拡張子だけが違うpage.tsや、_parts/のように_で始まるディレクトリの中のファイルも同じです。そのディレクトリにページが無ければ、declares no routeのエラーも出ます。
直し方
部品はsrc/components/へ、それ以外のモジュールはsrc/lib/へ移し、importを書き換えます。ページなら拡張子を.tsxにします。
fallback.tsxの置き場所のエラー
原因
fallback.tsxは、パラメータを持つpage.tsxの横に置くファイルです。そうでない場所にあると、routes/<path>: fallback.tsx …の行がエラーに並びます。どちらのモードでも同じです。
直し方
横にpage.tsxが無いなら、ページのディレクトリへ移します。横のlayout.tsxは、1つ上のディレクトリへ移すか、中身をpage.tsxとfallback.tsxに入れます。パラメータの無いページのfallback.tsxは消します。上のレイアウトがすべてのパラメータを受け取るときも、fallback.tsxを消して値をpathsに並べます。
a params schema must validate synchronously
原因
paramsSchemaが非同期に検証しています。URLに当たるルートは描画の前に決まるので、スキーマの結果を待てません。
直し方
スキーマには値の形の検証だけを書きます。データがあるかどうかはページで確かめ、無ければnotFound()を呼びます。
'server-only' cannot be imported in client build
原因
server-onlyをimportしたモジュールが、Client Componentから読まれています。エラーの2行目から下が、そこに至ったimportの連鎖です。
直し方
Client Componentからは直接importせず、Server Componentで読んだ値をpropsで渡します。
Functions cannot be passed directly to Client Components
原因
Server ComponentからClient Componentへ、関数をpropsで渡しています。propsはシリアライズして送るので、関数は渡せません。
直し方
関数を呼んだ結果の値を渡すか、関数をClient Componentの側へ移します。
useRoute must render inside a matched <Router>
原因
@k8ordo/routerからuseRoute()かuseParams()をimportしています。このフレームワークではブラウザがルート表を持たないので、2つのフックには読むルートがありません。
直し方
ページが受け取ったparamsを、propsでClient Componentに渡します。Client Componentの中では、useMatch()にパターンを渡しても読めます。