Skip to content

Conversation

Abdel-Monaam-Aouini
Copy link
Contributor

PR Description

🎯 Problem

Express v5 introduced stricter path parsing that requires wildcard routes to have named parameters. Previously valid syntax like app.all('*') now throws cryptic path-to-regexp errors:

TypeError: Missing parameter name at 1: https://git.new/pathToRegexpError

This creates a poor developer experience when migrating to Express v5, as users get unclear error messages without guidance on how to fix their code.

Solution

This PR enhances Express to catch path-to-regexp errors related to missing parameter names and provide clear, actionable error messages that guide developers to the correct Express v5 syntax.

Before:

app.all('*', handler); 
// TypeError: Missing parameter name at 1: https://git.new/pathToRegexpError

After:

app.all('*', handler);
// TypeError: Invalid route path: "*". In Express v5, wildcard routes must have named parameters. Use "/*splat" instead of "*" or "/*". See Express v5 migration guide for details.

🔧 Changes Made

  1. Enhanced app.route() error handling - Catches path-to-regexp errors and provides helpful messages for wildcard syntax issues
  2. Enhanced app.use() error handling - Similar improvements for middleware path validation
  3. Precise wildcard detection - Uses regex to accurately identify problematic patterns (*, /*, /*/something) while preserving valid syntax (/*splat)
  4. Comprehensive test coverage - Added tests for both route and middleware wildcard error scenarios

📋 Error Message Features

  • ✅ Clear explanation that Express v5 requires named parameters
  • ✅ Specific suggestion to use /*splat instead of * or /*
  • ✅ Reference to Express v5 migration guide
  • ✅ Unique error codes for programmatic handling (INVALID_WILDCARD_ROUTE, INVALID_WILDCARD_PATH)
  • ✅ Preserves original error in originalError property

🧪 Testing

  • All existing tests pass - no breaking changes
  • New comprehensive test suite covers error handling for both app.all() and app.use()
  • Tests verify both error cases and continued functionality with valid wildcard syntax
  • Manual testing confirms the exact issue scenario from user reports is resolved

🎁 Benefits

  • Improved DX: Developers get clear, actionable error messages instead of cryptic path-to-regexp errors
  • Faster migration: Users can quickly identify and fix wildcard route issues when upgrading to Express v5
  • Backward compatibility: No breaking changes to existing valid code
  • Better debugging: Error codes enable programmatic error handling

📚 Related Issues

Fixes the wildcard route error issue described in multiple community reports and Stack Overflow questions regarding Express v5 migration difficulties.


Note: This enhancement only improves error messaging - it doesn't change Express v5's requirement for named wildcard parameters, which is the intended behavior per the migration guide.

Copy link
Member

@bjohansebas bjohansebas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

-1 on doing this here. We know the error message can be improved, but that would be the responsibility of path-to-regexp, not Express. Also, the message is already being improved in pillarjs/path-to-regexp#363 maybe that resolves part of the issue.

@shivarm
Copy link
Contributor

shivarm commented Jul 31, 2025

@bjohansebas I agree

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants