State persistence: handling stale routes in react‑navigation

When a React Navigation app restarts, the navigator can be hydrated from a persisted state that was captured via onStateChange. This feature is documented in v6 and is intended to preserve the user’s navigation history across sessions.

However, if the persisted state contains routes that are no longer declared in the current navigator configuration, the library silently drops those routes during rehydration. The documentation does not expose an option to change this behavior, nor does it warn the developer when an unknown route is encountered.

Because the persisted state is retained until explicitly cleared, a removed route can remain in storage across app restarts, potentially causing navigation errors or blank screens when the app later attempts to navigate to that route.

Given this silent drop behavior, developers must manually manage persisted state when the route hierarchy changes. The unresolved decision is whether React Navigation should provide a configurable option to preserve unknown routes for backward compatibility, or continue to drop them automatically.

What are the implications of leaving stale routes in persisted state?

Should React Navigation expose a setting to preserve unknown routes during hydration?

What is the recommended approach to clear stale persisted state when modifying the navigator?