できない.dev

Express 5 で「Missing parameter name」が出てサーバーが起動できない

Missing parameter name は、/* を /*splat、/:id? を {/:id} に書き換えれば直る。
Express 5 の path-to-regexp 8 は、名前の無い * や ? を含むパスを登録時に例外にする。

公開: 更新:

症状できない · exit 1
node wildcard.js > wildcard.log 2>&1
…
                    throw new PathError(`Missing parameter name at index ${index}`, str);
                    ^
PathError [TypeError]: Missing parameter name at index 2: /*; visit https://git.new/pathToRegexpError for info

2026-10-27 に node:20(Express 5.3.0 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

Express 4 で動いていたルートを Express 5 で登録すると、app.listen() に届く前に次の例外でプロセスが終了する。

PathError [TypeError]: Missing parameter name at index 2: /*; visit https://git.new/pathToRegexpError for info

Express 5 はルートのパスの解析に path-to-regexp 8 を使っており、ワイルドカード * には :id と同じように名前が要る。
? による省略可能なパラメータや、( などの正規表現の文字もパスの文字列には書けなくなった。
移行ガイド(新しいタブで開く)の「Path route matching syntax」に変更点がまとまっている。

エラーの表記は path-to-regexp のバージョンで異なる。
上は Express 5.2.1 と、依存として入る path-to-regexp 8.4.2 での表示で、いま Express 5.0.1〜5.2.1 のどれを入れても同じ表示になった。
8.3.0 から例外のクラスが TypeError を継承した PathError に変わっており、上の表示の先頭が PathError [TypeError] になっているのはそのためだ。
8.2.0 では TypeError: Missing parameter name at 2: https://git.new/pathToRegexpError の形で出る。
どちらも末尾の URL は path-to-regexp の README のエラー一覧を指す。

実行例

node:20 のコンテナで Express 5.3.0 に /*・/user/:id?・/:section(discussion|page)/:slug を登録すると、どれも app.listen() の前に例外で落ちて終了コード 1 になった。
/*splat や /user{/:id} に書き直したサーバーは起動し、express@4 を入れ直すと /* もそのまま通った。

$ npm install --no-audit --no-fund express
added 65 packages in 1s
$ npm ls express path-to-regexp
missing-param-demo@ /tmp/tmp.xK7TZ5uP81
`-- express@5.3.0
  `-- router@2.2.0
    `-- path-to-regexp@8.4.2
$ node wildcard.js > wildcard.log 2>&1
$ echo $?
1
$ grep -v "^    at " wildcard.log
/tmp/tmp.xK7TZ5uP81/node_modules/path-to-regexp/dist/index.js:108
                    throw new PathError(`Missing parameter name at index ${index}`, str);
                    ^
 
PathError [TypeError]: Missing parameter name at index 2: /*; visit https://git.new/pathToRegexpError for info
  originalPath: '/*'
}
 
Node.js v20.20.2
$ node optional.js > optional.log 2>&1
$ echo $?
1
$ grep -v "^    at " optional.log
/tmp/tmp.xK7TZ5uP81/node_modules/path-to-regexp/dist/index.js:130
                throw new PathError(`Unexpected ${value} at index ${index - 1}`, str);
                ^
 
PathError [TypeError]: Unexpected ? at index 9: /user/:id?; visit https://git.new/pathToRegexpError for info
  originalPath: '/user/:id?'
}
 
Node.js v20.20.2
$ node regex.js > regex.log 2>&1
$ echo $?
1
$ grep -v "^    at " regex.log
/tmp/tmp.xK7TZ5uP81/node_modules/path-to-regexp/dist/index.js:130
                throw new PathError(`Unexpected ${value} at index ${index - 1}`, str);
                ^
 
PathError [TypeError]: Unexpected ( at index 9: /:section(discussion|page)/:slug; visit https://git.new/pathToRegexpError for info
  originalPath: '/:section(discussion|page)/:slug'
}
 
Node.js v20.20.2
$ node server.js > server.log 2>&1 &
$ cat server.log
listening on 3000
$ curl -s http://localhost:3000/files/a/b.txt
{"splat":["a","b.txt"]}
$ curl -s http://localhost:3000/user
{}
$ curl -s http://localhost:3000/user/42
{"id":"42"}
$ curl -s http://localhost:3000/page/hello
{"slug":"hello"}
$ curl -s http://localhost:3000/blog/hello
{"0":"blog","1":"hello"}
$ curl -s http://localhost:3000/
{"fallback":null}
$ npm install --no-audit --no-fund express@4
added 68 packages in 1s
$ node wildcard.js > server4.log 2>&1 &
$ cat server4.log
listening on 3000
$ curl -s http://localhost:3000/anything
ok

— 2026-10-27 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-27 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • Express 5.3.0

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. ワイルドカードに名前を付ける

// Express 4
app.get("/files/*", handler);
 
// Express 5
app.get("/files/*splat", handler);

一致した部分は req.params.splat に配列で入り、/files/a/b.txt なら ["a", "b.txt"] になる。
*splat は 1 文字以上に一致するので、/*splat はトップの / に一致しない。
トップも含めてすべてのパスに一致させたいときは、波括弧で囲んで /{*splat} と書く。

app.get("/{*splat}", (req, res) => {
  res.sendFile(path.join(__dirname, "dist", "index.html"));
});

2. 省略可能な部分は波括弧で囲む

// Express 4
app.get("/user/:id?", handler);
 
// Express 5(/user と /user/42 の両方に一致する)
app.get("/user{/:id}", handler);

波括弧の中は丸ごと省略できる。
拡張子を省略可能にするなら /:file{.:ext} と書く。

3. 正規表現が要るときは配列か正規表現リテラルで渡す

// パスを候補ごとに並べる
app.get(["/discussion/:slug", "/page/:slug"], handler);
 
// 正規表現リテラルで渡す(キャプチャは req.params[0] と req.params[1] に入る)
app.get(/^\/(discussion|page)\/([^/]+)$/, handler);

正規表現の文字が使えないのは文字列で渡した場合で、RegExp をそのまま渡すことはできる。

4. 移行を後回しにするなら 4 系を指定する

npm install express@4

4 系は 5.1.0 が latest になった時点で保守フェーズ(MAINTENANCE)に移っている。
4 系に固定するのは移行までのつなぎとし、パスの書き換えを済ませたら 5 系に戻す。

よくある原因

  1. * に名前を付けていない。
    Express 4 時代の記事でよく見る app.get('*', ...)(SPA のフォールバック)や app.use('/api/*', ...) が、そのまま例外になる。
  2. ? で省略可能なパラメータを書いている。
    /user/:id? は Unexpected ? で始まる例外になる。
  3. パスの文字列に正規表現の文字を書いている。
    /:section(discussion|page)/:slug のような書き方は Unexpected ( で始まる例外になる。
  4. 5 系が入ったことに気付いていない。
    2025 年 3 月末に npm の latest タグが 5.1.0 に切り替わり、バージョンを指定しない npm install express で 5 系が入るようになった。