Failed to serialize configuration cache entry: Configuration Cache serialization failure with custom task classes

Context

The Gradle Configuration Cache aims to eliminate configuration-phase bottlenecks by caching the build graph, but it requires all build logic to be serializable. Custom task classes that capture non-transient state — such as file handles, database connections, or mutable collections — trigger the error "Failed to serialize configuration cache entry" when the cache attempts to persist the configuration result.

Constraints and uncertainty

Third-party plugin compatibility remains inconsistent; many plugins still ship non-serializable types or rely on APIs that bypass the cache's requirements. The cache invalidation strategy for environment changes (JDK version, system properties, environment variables) is not fully documented, so a cache entry that serializes successfully on one machine may be silently discarded on another. Parallel execution compounds the problem by increasing memory pressure during the serialization phase, which can mask the root cause of a serialization failure.

Open questions

1. What is the minimal set of Gradle APIs and plugin versions that guarantee a configuration-cache-compatible build without refactoring every custom task?
2. How can a team reliably measure the configuration-phase bottleneck before committing to the refactoring effort required for full serialization compliance?
3. Which environment-change scenarios are officially supported for cache reuse, and where does the current documentation leave gaps that cause unexpected misses?