carrierwaveuploader/carrierwave · error · NotImplementedError

Need to implement #clean_cache! if you want to use #{self.cl

Error message

Need to implement #clean_cache! if you want to use #{self.class.name} as a cache storage.

What it means

NotImplementedError raised by the clean_cache! stub on CarrierWave::Storage::Abstract. It fires when cache expiry is requested — usually the CarrierWave.clean_cached_files! rake task / Uploader::Base.clean_cached_files! — and the configured cache storage engine never implemented timed cleanup of the cache directory.

Source

Thrown at lib/carrierwave/storage/abstract.rb:39

      end

      def retrieve!(identifier)
      end

      def cache!(new_file)
        raise NotImplementedError, "Need to implement #cache! if you want to use #{self.class.name} as a cache storage."
      end

      def retrieve_from_cache!(identifier)
        raise NotImplementedError, "Need to implement #retrieve_from_cache! if you want to use #{self.class.name} as a cache storage."
      end

      def delete_dir!(path)
        raise NotImplementedError, "Need to implement #delete_dir! if you want to use #{self.class.name} as a cache storage."
      end

      def clean_cache!(seconds)
        raise NotImplementedError, "Need to implement #clean_cache! if you want to use #{self.class.name} as a cache storage."
      end
    end # Abstract
  end # Storage
end # CarrierWave

View on GitHub (pinned to b5f0abe10e)

Solutions

1. Set config.cache_storage = :file and let the built-in File storage clean its cache dir
2. Implement #clean_cache!(seconds) in your storage subclass (delete entries older than the cutoff)
3. Skip/scope clean_cached_files! to uploaders whose cache storage actually supports it

Example fix

# before
# lib/tasks/carrierwave.rake
task :clean_cache => :environment do
  CarrierWave.clean_cached_files! # NotImplementedError with store-only storage
end

# after
task :clean_cache => :environment do
  CarrierWave.configure { |c| c.cache_storage = :file }
  CarrierWave.clean_cached_files!
end

MyUploader.clean_cached_files! if (MyUploader.cache_storage || MyUploader.storage).instance_methods.include?(:clean_cache!)

def cache_capable_storage?(klass)
  %i[cache! retrieve_from_cache! delete_dir! clean_cache!].all? { |m| klass.instance_methods.include?(m) }
end

When it happens

Trigger: Running CarrierWave.clean_cached_files! (scheduled rake task or cron) while the resolved cache storage (self.class.cache_storage || self.class.storage) is an engine without clean_cache! — e.g. a custom store-only storage, or cache_storage pointing at a non-file engine on versions lacking implementations.

Common situations: Adding the standard daily cache-cleaning cron after switching storages; custom storage engines built only for store/retrieve; CI running the maintenance task against a stub storage.

Related errors

• Need to implement #cache! if you want to use #{self.class.na
• Need to implement #retrieve_from_cache! if you want to use #
• Need to implement #delete_dir! if you want to use #{self.cla
• invalid cache id
• invalid filename

AI-assisted analysis of carrierwaveuploader/carrierwave@b5f0abe10e (2026-08-21). Data as JSON: /api/errors/0d1cdb1b5f7026b3. Report an issue: GitHub.