Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

Never is the bottom type in Dart’s static type system. It represents an expression that can never successfully complete evaluation, meaning a value of type Never can never exist at runtime.

​
Type Hierarchy and Generics

In type theory, a bottom type is a subtype of all other types. Because Never sits at the absolute bottom of Dart’s type hierarchy, an expression of type Never can be assigned to a variable of any other type. Conversely, no type is a subtype of Never (except Never itself). This subtyping behavior extends to generics, where Never acts as a strict constraint. For example, a List<Never> represents a list that is guaranteed to be empty because it can never accept elements. Similarly, a Stream<Never> represents a stream that can only emit errors or completion events, never data. Under Dart’s sound null safety, Never is strictly non-nullable. Its nullable counterpart, Never?, represents a type that can only ever contain null, making Never? functionally equivalent to the Null type.

​
Execution Mechanics and Reachability

When a function is declared with a return type of Never, the Dart analyzer enforces that the function cannot return normally. The analyzer verifies this purely through reachability analysis. To satisfy the compiler, the end of the function block must be unreachable. This is achieved by:
  1. Executing a throw or rethrow statement.
  2. Entering an unconditionally infinite loop.
  3. Calling another expression statically typed as Never (such as exit() or Isolate.exit(), which satisfy the analyzer simply because their signatures declare a Never return type).
Because the compiler guarantees a Never expression will halt normal control flow, any code written immediately after an expression evaluating to Never is statically analyzed as dead (unreachable) code.

​
Syntax Visualization

// A function returning Never must interrupt control flow.
Never haltExecution() {
  throw Exception('Execution terminated');
}

Never infiniteLoop() {
  while (true) {
    // Infinite execution prevents normal return
  }
}

// Because Never is a subtype of all types, an expression evaluating 
// to Never can satisfy any static type requirement.
void assignToInt() {
  int number = haltExecution();
}

void assignToString() {
  String text = haltExecution();
}

void deadCodeDemonstration() {
  haltExecution();
  
  // The analyzer flags the following as dead code because 
  // the preceding Never expression halts control flow.
  print('This will never execute'); 
}

​
Variable Declaration

While the syntax allows declaring a variable of type Never, it is impossible to initialize or assign a value to it, as no instance of Never can be instantiated in memory. 
// Valid static declaration, but impossible to populate at runtime.
late Never impossibleValue;
Master Dart with Deep Grasping Methodology!Learn More