TaskStatus enum

Current status of a task.

Represents the lifecycle state of a scheduled task. Query task status using NativeWorkManager.getTaskStatus.

Task Lifecycle

PENDING → RUNNING → COMPLETED
                  → FAILED
        → CANCELLED

Checking Task Status

final status = await NativeWorkManager.getTaskStatus(taskId: 'upload-photos');

switch (status) {
  case TaskStatus.pending:
    print('Waiting for WiFi...');
    break;
  case TaskStatus.running:
    print('Upload in progress...');
    break;
  case TaskStatus.completed:
    print('Upload finished!');
    break;
  case TaskStatus.failed:
    print('Upload failed - will retry');
    break;
  case TaskStatus.cancelled:
    print('Upload cancelled by user');
    break;
  case null:
    print('Task not found');
    break;
}

Monitoring Multiple Tasks

Future<void> checkUploads() async {
  final tasks = await NativeWorkManager.getTasksByTag(tag: 'upload');

  final pending = tasks.where((t) => t.status == TaskStatus.pending).length;
  final running = tasks.where((t) => t.status == TaskStatus.running).length;
  final completed = tasks.where((t) => t.status == TaskStatus.completed).length;

  print('Uploads: $pending pending, $running active, $completed done');
}

Status Transitions

PENDING → RUNNING:

  • Constraints are met (network, battery, etc.)
  • OS scheduler starts execution
  • Task begins doing work

RUNNING → COMPLETED:

  • Worker returns success result
  • All work finished successfully
  • Task removed from queue

RUNNING → FAILED:

  • Worker throws exception
  • Network error, timeout, etc.
  • OS may retry automatically (periodic tasks)

ANY → CANCELLED:

Important Notes

  • Completed tasks are automatically removed after a short period (OS-dependent)
  • Failed periodic tasks may be retried automatically by the OS
  • Cancelled tasks cannot be resumed - must enqueue again
  • Running tasks may take time to fully stop when cancelled

See also:

Inheritance
Available extensions

Values

pending → const TaskStatus

Task is waiting to be executed.

The task is scheduled but constraints are not yet met (e.g., waiting for WiFi, charging, etc.).

running → const TaskStatus

Task is currently running.

The worker is actively executing. Listen to NativeWorkManager.progress for real-time progress updates.

completed → const TaskStatus

Task completed successfully.

The worker finished and returned success. Completed tasks are automatically removed from the queue after a short period.

failed → const TaskStatus

Task failed.

The worker threw an exception or returned failure. For periodic tasks, the OS may automatically retry. For one-time tasks, the task is marked as failed and removed from the queue.

cancelled → const TaskStatus

Task was cancelled.

The task was explicitly cancelled via NativeWorkManager.cancel, NativeWorkManager.cancelByTag, or NativeWorkManager.cancelAll. Cancelled tasks are removed from the queue and cannot be resumed.

paused → const TaskStatus

Task is paused.

The task was paused via NativeWorkManager.pause or NativeWorkManager.pauseByTag. Resume with NativeWorkManager.resume.

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<TaskStatus>
A constant List of the values in this enum, in order of their declaration.