Stale code insight after external changes, VFS and PSI cache invalidation

IntelliJ IDEA maintains persistent indices and in-memory PSI structures for fast code insight. Updates are incremental and tied to VFS events and OS file system notifications.

The design relies on notifications rather than polling, which creates a trade-off between freshness and resource consumption. Changes made outside the IDE, on network drives, Docker volumes, or by external build tools can leave indices and PSI out of sync until the IDE refreshes its view.

Symptoms are component-specific and non-deterministic, such as unresolved symbols, outdated Find Usages results, or stale run configuration metadata. Manual cache invalidation is documented as the supported recovery path for persistent stale results, indicating automatic invalidation is intentionally limited.

Behavior is version-sensitive across IntelliJ Platform releases and IDE variants, and stale results may reflect intentional delayed indexing or pending background tasks rather than corruption.

What conditions cause the VFS to defer or miss invalidation for externally modified files? How is the balance between aggressive file system watching and resource usage defined for network and containerized paths? Which signals distinguish intentional delayed indexing from a stale cache state?