PyCharm code insight inconsistency and stale index cache

Answer first

No. PyCharm does not expose a public programmatic API for users to verify index integrity without a full manual invalidation. The primary user-facing remediation remains File > Invalidate Caches... with restart. There is no documented, supported command or script that returns an integrity status for the internal file-based indices.

Confirmed facts

• Implicit cleanup is triggered internally when checksum mismatches are detected in index files or when project structure changes are detected via the IDE file-system watcher.
• The IDE relies on a file-system watcher to detect external modifications. Files changed outside the IDE are typically re-indexed on open or on window focus, not instantly.
• Silent corruption where the IDE believes the index is valid but code insight is inaccurate is resolved by Invalidate Caches. The UI does not proactively flag a stale cache state.
• Internal indexing errors are only observable via logs at Help > Show Log. The UI does not surface index corruption as a distinct notification.

Likely explanation vs confirmed

Confirmed: no public verification API exists. Likely, but not officially documented, is that rapid external edits can overwhelm the watcher, leading to stale indices that the IDE does not automatically invalidate. This is an inference from observed behavior, not a documented guarantee.

Steps needed for this case

1. Check logs for indexing failures. Open Help > Show Log and search for entries containing Indexing or Corruption.
2. Verify watcher behavior. Modify a file with an external editor, then open the file in PyCharm and observe if completion and navigation update.
3. If insight remains inaccurate, run File > Invalidate Caches... and restart. This is the supported recovery path for suspected silent corruption.

Assumption: the project is large enough that full re-indexing is costly. Uncertainty remains around exact checksum validation thresholds, which are internal to the IntelliJ platform and not published.

One diagnostic detail that changes the recommendation: is the inconsistency appearing after files are modified by external processes, or after an IDE update / project import? External process churn suggests watcher limits; post-update suggests index format mismatch requiring invalidation.