instructure/canvas-lms · error · Attachment::OverQuotaError

The downloaded file exceeds the quota.

Error message

The downloaded file exceeds the quota.

What it means

Attachment#clone_url downloads a remote URL into this attachment. When check_quota is enabled and, after saving to compute size, Attachment.over_quota? reports the context would exceed its storage quota, it raises OverQuotaError with 'The downloaded file exceeds the quota.' The download already happened; the error aborts making the file available.

Solutions

1. Free up storage in the context (delete unneeded files) or raise the quota before retrying
2. Download a smaller file or skip quota check explicitly if policy allows (check_quota: false)
3. Pass the correct opts[:quota_context] so the right context's quota is evaluated
4. Rescue Attachment::OverQuotaError in the controller/job and show a quota-exceeded message with usage details

Example fix

// before
attachment.clone_url(url, 'rename', true)
// after
begin
  attachment.clone_url(url, 'rename', true)
rescue Attachment::OverQuotaError
  notify_user_of_quota_exceeded(context)
end

// check remaining quota before initiating download
used = context.attachments.sum(:size)
remaining = context.storage_quota - used
if remaining <= 0 raise Attachment::OverQuotaError

begin
  attachment.clone_url(url, 'rename', true)
rescue Attachment::OverQuotaError => e
  render json: { error: e.message, quota: context.storage_quota }, status: :insufficient_storage
end

When it happens

Trigger: Calling clone_url (or_clone/clone_to helpers) with check_quota=true on a context whose remaining quota is smaller than the downloaded file's size; importing a large file via submission/import APIs into a nearly full course/account/user quota.

Common situations: Course or user storage quota exhausted; institutional account quotas tightened while old imports still run; large media migrations exceeding per-context limits; quota_context passed incorrectly so a tiny quota is checked.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• Attachment verifier token expired: #
• Attachment verifier token id mismatch. token id: #
• Attachment verifier token invalid: #
• failed to reclaim attachment #
• File exceeds # byte limit

AI-assisted analysis of instructure/canvas-lms@1c9f0bb801 (2026-09-15). Data as JSON: /api/errors/977e413f21475276. Report an issue: GitHub.

Appendix: source

Thrown at app/models/attachment.rb:2414

    {
      tags: {
        type: CLONING_ERROR_TYPE
      },
      extra: {
        http_status_code: error.try(:code),
        body: error.try(:body),
        url:
      }.compact
    }
  end

  def clone_url(url, duplicate_handling, check_quota, opts = {})
    Attachment.clone_url_as_attachment(url, attachment: self)

    if check_quota
      save! # save to calculate attachment size, otherwise self.size is nil
      if Attachment.over_quota?(opts[:quota_context] || context, size)
        raise OverQuotaError, t(:over_quota, "The downloaded file exceeds the quota.")
      end
    end

    self.file_state = "available"
    save!

    # the UI only needs the id from here
    opts[:progress]&.set_results({ id: })

    handle_duplicates(duplicate_handling || "overwrite")
    nil # the rescue returns true if the file failed and is retryable, nil if successful
  rescue => e
    failed_retryable = false
    self.file_state = "errored"
    self.workflow_state = "errored"
    case e
    when CanvasHttp::TooManyRedirectsError
      failed_retryable = true

View on GitHub (pinned to 1c9f0bb801)