carrierwaveuploader/carrierwave · error · CarrierWave::IntegrityError

errors.messages.max_size_error

Error message

errors.messages.max_size_error

What it means

CarrierWave raises CarrierWave::IntegrityError with this message from the `before :cache` callback `check_size!` when the uploaded file exceeds the maximum of the Range returned by the uploader's `size_range` (bytes). It only fires when `size_range` returns a `::Range`; the maximum is humanized via `number_to_human_size` in the message. The check happens at cache time — when the file is assigned, before storage — so oversized uploads fail before any storage backend is touched.

Source

Thrown at lib/carrierwave/uploader/file_size.rb:36

      #
      # === Examples
      #
      #     def size_range
      #       3256...5748
      #     end
      #
      def size_range; end

    private

      def check_size!(new_file)
        size = new_file.size
        expected_size_range = size_range
        if expected_size_range.is_a?(::Range)
          if size < expected_size_range.min
            raise CarrierWave::IntegrityError, I18n.translate(:"errors.messages.min_size_error", :min_size => ActiveSupport::NumberHelper.number_to_human_size(expected_size_range.min))
          elsif size > expected_size_range.max
            raise CarrierWave::IntegrityError, I18n.translate(:"errors.messages.max_size_error", :max_size => ActiveSupport::NumberHelper.number_to_human_size(expected_size_range.max))
          end
        end
      end

    end # FileSize
  end # Uploader
end # CarrierWave

View on GitHub (pinned to b5f0abe10e)

Solutions

1. Raise the maximum in `size_range` to match the real business limit (e.g. `0..20.megabytes`).
2. Mirror the same limit upstream: HTML `accept`/client-side File.size checks and server/proxy body limits (e.g. nginx `client_max_body_size`), so users get early feedback instead of an exception.
3. Compress or downscale client-side before upload if the limit must stay.
4. Rescue `CarrierWave::IntegrityError` at assignment and present `e.message` (it already contains the humanized max) as a form error.

Example fix

# before
class AvatarUploader < CarrierWave::Uploader::Base
  def size_range
    0..1.megabyte
  end
end
# uploading a 6 MB photo => CarrierWave::IntegrityError: max_size_error

# after
class AvatarUploader < CarrierWave::Uploader::Base
  def size_range
    0..10.megabytes
  end
end

max = 5.megabytes  # keep in sync with the uploader's size_range
if uploaded_io.respond_to?(:size) && uploaded_io.size > max
  errors.add(:avatar, :too_large, count: ActiveSupport::NumberHelper.number_to_human_size(max))
end

begin
  user.avatar = params[:avatar]
rescue CarrierWave::IntegrityError => e
  # e.message is max_size_error with the humanized maximum, safe to show to users
  errors.add(:avatar, message: e.message)
end

When it happens

Trigger: Defining `def size_range; 0..5.megabytes; end` and assigning a 12 MB file (`new_file.size > range.max`). Also common when the browser/server allows big multipart bodies but CarrierWave's range is tighter, so the failure appears as an exception during `update`/`create` rather than at the HTTP layer.

Common situations: Modern phone photos (5–15 MB HEIC/JPEG) exceeding a legacy `1.megabyte` cap; nginx `client_max_body_size` raised to fix 413s, only for the exception to move into the app as this IntegrityError; direct-to-S3 or chunked upload flows where the final assembled file bypasses or re-enters the size check; range written with an exclusive end (`3256...5748`) so exactly-max files are accepted but max+1 rejected as expected.

Related errors

• errors.messages.min_size_error
• errors.messages.extension_allowlist_error
• errors.messages.extension_denylist_error
• Version #{version} doesn't exist!
• could not download file: #{e.message}

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