UploadErrorCode enum

Enum representing the various errors that can occur during file upload preparation or processing within the StorageUpload system.

Each value corresponds to a specific failure point during the upload pipeline, from file validation to metadata extraction.

Example usage:

throw UploadException(
  UploadErrorCode.fileTooLarge,
  'The selected file exceeds the 50MB upload limit.',
);
Inheritance
Available extensions

Values

unsupportedExtension → const UploadErrorCode

The file has an unsupported extension and is not allowed for upload.

This typically occurs when the file has a potentially dangerous or disallowed extension such as .exe, .bat, or .sh. It may also fail if the file does not match any known supported type (e.g. image, audio, video, or document).

Common usage:

  • Validation step before upload.
  • Preventing malicious or irrelevant file formats.

Example disallowed extensions: .exe, .bat, .dll, .ps1

fileTooLarge → const UploadErrorCode

The file exceeds the maximum allowed size for upload.

This error occurs when the file’s size surpasses the configured threshold (e.g. 2 GB limit for large media uploads). The threshold can vary depending on system configuration or Firebase limitations.

Useful to prevent memory pressure, bandwidth exhaustion, or service-side rejection.

Example:

  • A 2.5GB video is rejected when the limit is 2GB.
fileNotFound → const UploadErrorCode

The file was not found at the expected local path.

This happens when the file no longer exists on the filesystem, has been deleted manually, or the path is incorrect/missing.

This should trigger cleanup logic or show an error in the UI to the user.

Example scenarios:

  • The user selected a file and then deleted it before upload.
  • A stale file path is reused after an app restart.
unreadableFile → const UploadErrorCode

The file exists but could not be read.

This often indicates a permission issue, locked file, or corrupt disk entry. Even though the path exists, reading its bytes fails.

Example cases:

  • File is protected by OS-level permissions.
  • File is locked by another process or app.
  • I/O exception during read attempt.
unsupportedMime → const UploadErrorCode

The MIME type of the file is not supported for upload.

This occurs when the file’s detected MIME type (e.g. application/x-msdos-program) does not match the list of acceptable types (like images, audio, videos, etc.).

This check prevents unsupported formats from entering the system.

Example unsupported types:

  • application/x-msdos-program
  • application/octet-stream (if type cannot be determined)
blurHashFailed → const UploadErrorCode

Failed to generate a BlurHash for the file.

This typically affects images or videos when the system attempts to generate a visual placeholder using the BlurHash algorithm.

Failure may result from:

  • Invalid or corrupt pixel data.
  • Unsupported file format for decoding.
  • Conversion errors.

This is not a blocking error for upload, but may impact UI display.

imageDecodingFailed → const UploadErrorCode

The image could not be decoded to extract metadata.

This prevents operations like retrieving width, height, orientation, or generating previews.

This may be due to:

  • A corrupt file.
  • Unsupported encoding.
  • Incomplete download.

Upload may continue without metadata, but features relying on it will break.

videoMetadataFailed → const UploadErrorCode

Failed to extract metadata from the video file.

This includes properties like duration, resolution, or orientation, which are commonly used for UI rendering or analytics.

May occur due to:

  • Corrupt video headers.
  • Incompatible codec.
  • Missing read permissions.

Upload may still succeed, but without full context or accurate previews.

audioMetadataFailed → const UploadErrorCode

The specified object could not be found in the remote storage.

Corresponds to Firebase code: storage/object-not-found.

objectNotFound → const UploadErrorCode

The specified object could not be found in the remote storage.

Corresponds to Firebase code: storage/object-not-found.

bucketNotFound → const UploadErrorCode

The specified storage bucket does not exist or is not accessible.

Corresponds to Firebase code: storage/bucket-not-found.

projectNotFound → const UploadErrorCode

The Firebase project associated with the request could not be located.

Corresponds to Firebase code: storage/project-not-found.

quotaExceeded → const UploadErrorCode

The storage quota for the project has been exceeded.

Corresponds to Firebase code: storage/quota-exceeded.

unauthenticated → const UploadErrorCode

The operation failed because the user is not authenticated.

Corresponds to Firebase code: storage/unauthenticated.

unauthorized → const UploadErrorCode

The user does not have permission to perform the requested operation.

Corresponds to Firebase code: storage/unauthorized.

retryLimitExceeded → const UploadErrorCode

The maximum number of retry attempts has been exceeded.

Corresponds to Firebase code: storage/retry-limit-exceeded.

canceled → const UploadErrorCode

The upload operation was canceled by the user or system.

Corresponds to Firebase code: storage/canceled.

invalidChecksum → const UploadErrorCode

The uploaded file's checksum did not match the expected value, indicating possible data corruption.

Corresponds to Firebase code: storage/invalid-checksum.

invalidUrl → const UploadErrorCode

The provided URL for the storage resource is invalid or malformed.

Corresponds to Firebase code: storage/invalid-url.

invalidArgument → const UploadErrorCode

The operation received an invalid argument, such as a malformed path.

Corresponds to Firebase code: storage/invalid-argument.

networkError → const UploadErrorCode

The operation failed due to a network connectivity issue, such as no internet access.

This value is generated by the application when offline or when a remote service is unreachable.

unknown → const UploadErrorCode

An unknown or unclassified error occurred.

This is used as a fallback when no specific error code is matched.

Properties

hashCode → int
The hash code for this object.
no setterinherited
index → int
A numeric identifier for the enumerated value.
no setterinherited
name → String

Available on Enum, provided by the EnumName extension

The name of the enum value.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

values → const List<UploadErrorCode>
A constant List of the values in this enum, in order of their declaration.