うまく動かないとき
よくつまずく症状と、その原因、直し方をまとめています。
このページの内容
static build needs pathnames for …でビルドが止まる
原因
パラメータを持つルートに当てはまるURLが、pathsに1つもありません。ビルドはパラメータの値を自分では決められません。
直し方
framework()のpathsで、そのルートのURLを並べます。
the "paths" option supplied pathnames no route wantsでビルドが止まる
原因
pathsが返したURLのうち、どのルートにも当たらないものがあります。多くはURLの打ち間違いです。
直し方
エラーの後ろに並んだURLを直すか、pathsから外します。
static build cannot ship Server Actionsでビルドが止まる
原因
'use server'を書いたモジュールがあります。ファイルはフォームの送信を受け取れないので、このモードではServer Actionを使えません。
直し方
フォームの送信をサーバーで受け取るなら、@k8ordo/serverに移ります。検索や絞り込みのようなGETのフォームなら、Server Actionを使わずに書けます。
static build cannot run guard.tsでビルドが止まる
原因
routes/の中にguard.tsがあります。ファイルには、通すかどうかを決めるリクエストがありません。
直し方
リクエストを止める必要があるなら@k8ordo/serverに移り、そうでなければguard.tsを消します。
static build could not render …でビルドが止まる
原因
そのページを描いている途中で、Server Componentが例外を投げました。上にSuspenseの境界が無いクライアントコンポーネントが投げた場合も同じです。
直し方
投げられたメッセージが、この行より上にページのURLと一緒に出ています。それを手がかりに直します。
vite devでは表示されるページで、ビルドが止まる
原因
vite devはファイルを書かず、リクエストのたびにページを描きます。そのためpathsに無い値のページも描き、Server Componentが投げた例外にも500で答えて動き続けます。
直し方
公開する前にvite buildを通し、止まったときのメッセージに従って直します。
404.htmlが200のステータスで返る
原因
404.htmlの答えに付けるステータスは、ホスティングが決めます。ビルドが書けるのはページまでで、応答のステータスは書けません。
直し方
ホスティングの設定で、持っていないURLに404.htmlを404のステータスで返すようにします。
the "csp" option cannot go into a page's <meta> as it isというエラーが出る
原因
cspに、<meta>では効かないディレクティブか、'strict-dynamic'が入っています。<meta>で効かないのはframe-ancestorsとreport-uri、sandboxです。
直し方
<meta>で効かないディレクティブは、ホスティングのヘッダーで設定します。'strict-dynamic'は外してください。フレームワークのモジュールのスクリプトは、'self'で許されています。
hydrationに失敗したというエラーが、本番でだけ出る
原因
ルートレイアウトが描いた文書は、まるごとhydrationの対象です。CDNの中には、HTMLを書き換える機能を持つものがあります。Webフォントの埋め込みやメールアドレスの難読化、スクリプトの遅延読み込みなどを有効にしていると、Reactが受け取る木とHTMLが食い違います。
直し方
CDNのその機能を切ります。フォントやスクリプトは別のoriginからリンクせず、同じoriginから配信すると、書き換えられるものが無くなります。
href()のパスやページのparamsに型が付かない
原因
tsconfig.jsonのincludeが.k8ordo/を読んでいません。.k8ordoはドットで始まるので、".k8ordo"のようにディレクトリ名だけを書いたincludeは、このディレクトリを読み飛ばします。
直し方
includeに.k8ordo/**/*.tsのようにグロブで書きます。
cloneした直後だけ、paramsが文字列の型になる
原因
.k8ordo/は生成物でgitに入らないので、cloneした直後にはまだありません。ルート表が無いと、PagePropsのparamsはスキーマの出力ではなく、文字列として型が付きます。
直し方
tscの前に一度vite devかvite buildを動かして、.k8ordo/を書かせます。
routes/ holds only page.tsx, …でビルドが止まる
原因
routes/の中に、ルートのファイル名ではないファイルがあります。拡張子だけが違うpage.tsも同じです。
直し方
部品やデータは、_parts/のように_で始まるディレクトリへ移します。ページなら拡張子を.tsxにします。
a params schema must validate synchronouslyというエラーが出る
原因
paramsSchemaが非同期に検証しています。どのルートがURLに答えるかは描画の前に決めるので、スキーマの結果を待てません。
直し方
スキーマには値の形の検証だけを書きます。データがあるかどうかはページで確かめ、無ければnotFound()を投げます。
'server-only' cannot be imported in client buildでビルドが止まる
原因
server-onlyをimportしたモジュールが、クライアントコンポーネントから読まれています。エラーの2行目から下が、そこに至ったimportの連鎖です。
直し方
クライアントコンポーネントからは直接読まず、Server Componentで読んだ値をpropsで渡します。
Functions cannot be passed directly to Client Componentsというエラーが出る
原因
Server Componentからクライアントコンポーネントへ、関数をpropsとして渡しています。propsはシリアライズして運ぶので、関数は渡せません。
直し方
関数を呼んだ結果の値を渡すか、関数をクライアントコンポーネントの側へ移します。
useRoute must render inside a matched <Router>というエラーが出る
原因
フレームワークの下では、ブラウザはルート表を持ちません。ページの木はサーバーから届くからです。そのためuseRoute()とuseParams()には、読むルートがありません。
直し方
ページが受け取ったparamsを、propsでクライアントコンポーネントに渡します。今のURLはusePathname()で読みます。