Caching
Configure template caching, trusted cache, and query cache strategies
Overview
The Caching page provides controls for ColdFusion's various caching mechanisms, which are critical for optimal performance. Proper cache configuration can dramatically reduce server load and improve response times by eliminating redundant compilation and database queries. This page covers template caching, trusted cache mode, query caching, and the server cache engine.
Template Cache Settings
Maximum Number of Cached Templates
PurposeLimits how many compiled CFML templates are stored in memory
Default1024 templates
RecommendationLarge enough to hold your commonly accessed pages, small enough to avoid excessive reloading. Adobe suggests one page per MB of JVM heap as a starting point
Best PracticeMonitor cache hit ratio and increase if you see frequent evictions
Trusted Cache
PurposeWhen enabled, ColdFusion never checks if cached templates have been modified
DefaultDisabled
Production RecommendationEnable for maximum performance
Development RecommendationKeep disabled to see code changes immediately
ImpactEliminates file system checks on every request, significantly improving performance
Deployment ProcessClear the template cache after deploying new code (Clear Template Cache Now, or Clear Template Cache of Specific Folder)
Performance Gain10-30% reduction in request processing time
Trade-offMust manually clear cache after code changes
Cache Template in Request
PurposeChecks each requested file for changes only once per request instead of on every access within that request
RecommendationEnable if you include the same template multiple times per request
Use CaseRecursive includes or heavily reused utility templates
ImpactPrevents redundant file operations within a single request
Component Cache
PurposeCaches component path resolution so ColdFusion does not resolve the same component path again
DefaultEnabled
RecommendationAlways enable (disabling severely impacts performance)
ImpactUse Clear Component Cache Now if a component path must be resolved again; no server restart needed
Memory UsageLarger than template cache as CFCs include metadata
Save Class Files
PurposePersist compiled Java class files to disk
DefaultEnabled
RecommendationEnable in production to speed up server restarts. Adobe notes that disabling it is typically faster during development
ImpactFaster server startup as templates don't need full recompilation
LocationStored in the cfclasses folder (cfusion/wwwroot/WEB-INF/cfclasses) (source: Charlie Arehart)
CleanupPeriodically delete old class files during maintenance windows
Defaults verified in the ColdFusion 2025 Update 14 configuration (neo-runtime.xml, keys templateCacheSize, trustedCacheEnabled, componentCacheEnabled and saveClassFiles) shipped in Adobe's official Docker image. These are installer defaults, and Adobe's Secure Profile does not change them.
Query Caching Settings
Maximum Number of Cached Queries
PurposeLimits how many query result sets can be cached simultaneously
Default100 queries (verified in the ColdFusion 2025 Update 14 configuration, neo-datasource.xml, key
maxcachecount, shipped in Adobe's official Docker image)RecommendationSet based on your application's caching strategy (500-2000 for heavy use)
ImpactWhen the limit is reached, the oldest cached query is dropped. A value of 0 makes query caching unlimited
Memory ConsiderationEach cached query stores full result set in memory
Best PracticeUse cachedwithin attribute strategically on expensive queries
Use Internal Cache to Store Queries
PurposeWhen selected, cached queries are stored in ColdFusion's older internal query cache. When cleared (the default), cached queries are stored in the QUERY region of Ehcache
NotePer application,
this.cache.useInternalQueryCache and this.cache.querysize override these server settingsClear Template Cache Now
PurposeEmpties the template cache. ColdFusion reloads templates on the next request and recompiles them if they have changed
Use CaseAfter deploying code changes in production with trusted cache enabled
ImpactNext request for each template will recompile (temporary performance hit)
Narrower OptionClear Template Cache of Specific Folder limits the clear to one folder instead of the whole template cache
Clear Query Cache Now
PurposeFlush all cached query results
Use CaseWhen underlying data has changed and cached results are stale
Granular ControlUse
cachedwithin timespan for automatic expirationProgrammatic AlternativeUse
<cfobjectcache action="clear">Server Wide Cache Engine
Server Wide Cache Engine
PurposeSelects the default server wide caching engine: Ehcache, JCS, Redis, or Memcached. Applications can override it with
this.cache.engineDefaultEhcache
SizingMemcached adds Memcached Servers, Max idle time, Max life span, and Max elements fields. Redis adds Redis Server, Redis Server Port, Password, and Is Cluster. JCS can persist the cache to a data source
Use CaseChoose Memcached or Redis when cached objects must be shared across servers
Best Practices
Production Environment
- Enable trusted cache for maximum performance
- Set template cache size to accommodate all templates (monitor for evictions)
- Clear template cache after each code deployment
- Use query caching strategically with appropriate cachedwithin values
- Enable save class files to speed up restarts
- Monitor cache hit ratios and adjust sizes accordingly
- Set conservative memory limits to prevent OutOfMemory errors
- Document cache clearing procedures in deployment runbooks
Development Environment
- Disable trusted cache to see code changes immediately
- Keep template cache size moderate (1024-2048)
- Disable query caching or use very short timeouts
- Manually clear caches when debugging caching issues
- Test cache clearing procedures before production use
Security Considerations
- Ensure cached queries don't expose sensitive data longer than necessary
- Consider security implications of caching user-specific data
- Clear caches after security patches or sensitive code changes
- Implement cache key strategies that prevent cache poisoning
- Monitor for unusual cache behavior that might indicate attacks
Performance Tuning
- Trusted cache provides 10-30% performance improvement in production
- Query caching can reduce database load by 50-90% for read-heavy applications
- Monitor template cache evictions - increase size if evictions are frequent
- Use shorter cache timeouts for frequently changing data
- Balance cache size against available heap memory
- Profile application to identify best candidates for query caching
- Consider external caching solutions (Redis, Memcached) for distributed deployments
Common Issues and Solutions
Code Changes Not Appearing (Trusted Cache)
Symptom: Deployed code changes not visible to users
Solution:
- Cause: Trusted cache enabled, template cache not cleared
- Clear the template cache in the Administrator (all templates or a specific folder)
- Prevention: Automate cache clearing in deployment scripts
OutOfMemoryError with Large Caches
Symptom: Server crashes or becomes unresponsive
Solution:
- Cause: Cache sizes exceed available heap memory
- Reduce cache sizes or increase JVM heap memory
- Analysis: Use heap dumps to identify cache memory consumption
- Best Practice: Total cache memory should not exceed 30-40% of heap
Stale Query Results
Symptom: Users seeing outdated data
Solution:
- Cause: Query cache timeout too long or not clearing after data updates
- Reduce cachedwithin timespan or clear cache after updates
- Pattern: Clear all cached queries with
<cfobjectcache action="clear">, or use thecacheMaxIdleTimeattribute (new in ColdFusion 2025) to expire idle cached queries
Template Cache Thrashing
Symptom: High CPU usage, frequent recompilations
Solution:
- Cause: Template cache too small for application size
- Increase maximum number of cached templates
- Detection: Monitor cache hit ratio via server monitoring tools
- Target: Cache hit ratio should be 95%+
Inconsistent Behavior Across Cluster
Symptom: Different servers showing different versions of code
Solution:
- Cause: Cache cleared on some servers but not others
- Ensure cache clearing is performed on all cluster nodes
- Tool: Use cluster manager or deployment automation to clear all caches
Cache Clearing Strategies
Manual Cache Clearing
- Via Administrator: Click "Clear Template Cache Now" or "Clear Query Cache Now"
- Requires administrator login and manual action on each server
- Best for development or emergency situations
Programmatic Cache Clearing
Programmatic Cache Clearing
Clear cached queries and cached objects, or restart an application, from code
// To clear all cached queries, use the <cfobjectcache action="clear"> tag
// shown in the Tag-Based tab
// Remove items stored with cachePut()
cacheRemove("myCacheId");
// Stop the application; it restarts on the next request
applicationStop();<!--- Clear all cached queries --->
<cfobjectcache action="clear">
<!--- Remove items stored with cachePut() --->
<cfset cacheRemove("myCacheId")>
<!--- Stop the application; it restarts on the next request --->
<cfset applicationStop()>Deployment Script Integration
- Include cache clearing in deployment automation
- Make clearing the template cache in the Administrator a step in every deployment
- Verify cache was cleared on all cluster nodes
- Monitor for errors during cache clear operations
Monitoring Cache Performance
Key Metrics to Track
- Template Cache Hit Ratio: Should be 95%+ in production
- Template Cache Evictions: Frequent evictions indicate cache too small
- Query Cache Size: Monitor memory consumption
- Query Cache Hit Ratio: Varies by application (50-90% typical)
- Compilation Time: Spikes indicate cache clears or evictions
Monitoring Tools
- Performance Monitoring Toolset (PMT), included with Standard and Enterprise and installed separately
- FusionReactor APM (third-party, highly recommended)
- Custom logging via GetMetricData()
- JVM monitoring tools (JConsole, VisualVM)