This page lists all language and library breaking changes and deprecations in Dart, organized by release and area, to help Dart users understand and manage their impact. Complete release notes are available in the Dart SDK changelog. The breaking change policy document describes the policy and process around breaking changes and deprecations in Dart.

This page includes the following types of breaking changes:

• Unversioned: The Dart SDK does not maintain backward compatibility, and code may break as soon as you upgrade your sdk version if it relies on the previous behavior.

  These are the majority of changes and are not specially marked in this list.

• Language versioned: The Dart SDK maintains backward compatibility for existing code, and the behavior change only takes effect (potentially breaking code that relies on the previous behavior) when you upgrade the language version of your code.

  These are marked “Language versioned“.

• Deprecations: The Dart SDK maintains compatibility for deprecated code, with a warning. Deprecations are then completely removed in a subsequent release, breaking any code that relies on the previous behavior.

  These are marked “Deprecated” and “Removed”, respectively.

• Experimental: Part of the release but not yet treated as stable in the SDK, and can break from one version to another. Experimental changes do not always have a corresponding breaking change issue, but may have more detail in the SDK changelog.

  These are marked “Experimental”, possibly in conjunction with another change type.

If you have questions or concerns about any of these breaking changes, please comment on the breaking change issue linked from the relevant entry. To be notified about future breaking changes, join the Dart announce group.

Not yet released to stable

Libraries

dart:nativewrappers

• Marked classes belonging to NativeWrapperClass as base so that none of their subtypes can be implemented.

dart:typed_data

• Deprecated: Unmodifiable view classes for typed data.

Released in 3.2.0

Language

• Language versioned: Changed the split point for refutable patterns to the top level pattern so type promotion in if-case statements is consistent regardless of whether the scrutinee might throw an exception.

Libraries

dart:cli

• Experimental Deprecated: The waitFor function.

dart:convert

• Changed return types of utf8.encode() and Utf8Codec.encode() from List<int> to Uint8List.

dart:developer

• Deprecated: The Service.getIsolateID method.

dart:ffi

• Changed NativeCallable.nativeFunction so calls now throw an error if the receiver is already closed, instead of returning nullptr.

dart:io

• Eliminated trailing whitespace from HTTP headers.
• Inserted a space at the fold point of folded header values that HttpClientResponse.headers and HttpRequest.headers return.

dart:js_interop

• Experimental Removed: JSNumber.toDart in favor of toDartDouble and toDartInt.
• Experimental Removed: Object.toJS in favor of Object.toJSBox.
• Experimental: Restricted external JS interop APIs using dart:js_interop to a set of allowed types.
• Experimental: Prohibited use of isNull and isUndefined on dart2wasm.
• Experimental: Changed typeofEquals and instanceof APIs to both return bool instead of JSBoolean. Also, typeofEquals now takes String instead of JSString.
• Experimental: Changed JSAny and JSObject types to only implementable, not extendable, by user @staticInterop types.
• Experimental: Changed JSArray.withLength to take int instead of JSNumber.

Tools

Development JavaScript compiler (DDC)

• Added interceptors for JavaScript Symbol and BigInt types; they should no longer be used with package:js classes.

Production JavaScript compiler (dart2js)

• Added interceptors for JavaScript Symbol and BigInt types; they should no longer be used with package:js classes.

Analyzer

• Language versioned: Private final field promotion might cause the following analyzer warnings to trigger on existing code that previously passed analysis:

  • unnecessary_non_null_assertion
  • invalid_null_aware_operator
  • unnecessary_cast

  class C {
    final num? _x = null;
  
    void test() {
      if (_x != null) {
        print(_x! * 2); // unnecessary_non_null_assertion
        print(_x?.abs()); // invalid_null_aware_operator
      }
      if (_x is int) {
        print((_x as int).bitLength); // unnecessary_cast
      }
    }
  }
  

Released in 3.1.0

Libraries

dart:async

• Added interface modifier to purely abstract classes: MultiStreamController, StreamConsumer, StreamIterator and StreamTransformer.

dart:io

• Added sameSite to the Cookie class, and added the class SameSite.
• FileSystemEvent is sealed. This means FileSystemEvent cannot be extended or implemented.

dart:js_interop

• Experimental Removed: ObjectLiteral; create an object literal with no named members using {}.jsify().

package:js

• external @staticInterop members and external extension members can no longer be used as tear-offs. Declare a closure or a non-external method that calls these members, and use that instead.
• external @staticInterop members and external extension members will generate slightly different JS code for methods that have optional parameters.

Released in 3.0.0

Language

• Language versioned: Changed interpretation of switch cases from constant expressions to patterns.

• Language versioned: Class declarations from libraries that have been upgraded to Dart 3.0 can no longer be used as mixins by default.

• Dart reports a compile-time error if a continue statement targets a label that is not a loop (for, do and while statements) or a switch member.

Libraries

• The following existing classes have been made mixin classes: Iterable, IterableMixin, IterableBase, ListMixin, SetMixin, MapMixin, LinkedListEntry, StringConversionSink.

dart:core

• Deprecated: Deprecated APIs.

dart:async

• Removed: Removed the deprecated DeferredLibrary class.

dart:collection

• Language versioned: Changes to platform libraries.

dart:developer

• Removed: Removed the deprecated MAX_USER_TAGS constant. Use maxUserTags instead.
• Removed: Removed the deprecated Metrics, Metric, Counter, and Gauge classes as they have been broken since Dart 2.0.

dart:html

• Removed: Removed the deprecated registerElement and registerElement2 methods in Document and HtmlDocument.

dart:math

• Language versioned: The Random interface can only be implemented, not extended.

dart:io

• Updated NetworkProfiling to accommodate new String ids that are introduced in vm_service:11.0.0

Released in 2.19.0

Language

• Flagged additional code as unreachable due to types Null and Never.
• Don’t delegate inaccessible private names to noSuchMethod.
• Report a compile-time error for all cyclic dependencies during top-level type inference.

Libraries

dart:convert

• Removed: The previously deprecated API [DEFAULT_BUFFER_SIZE] in JsonUtf8Encoder has been removed.

dart:developer

• Removed: Removed previously deprecated APIs kInvalidParams, kExtensionError, kExtensionErrorMax, and kExtensionErrorMin in ServiceExtensionResponse.

dart:ffi

• Changed the runtime type argument of Pointer to Never in preparation of completely removing the runtime type argument. Changed Pointer.toString to not report any type argument.

dart:io

• Disallow negative or hexadecimal content-length headers.
• File.create now takes new optional exclusive bool parameter, and when it is true the operation will fail if target file already exists.
• Calling ResourceHandle.toFile(), ResourceHandle.toSocket(), ResourceHandle.toRawSocket() or ResourceHandle.toRawDatagramSocket(), more than once now throws a StateError.

dart:isolate

• Reverted SendPort.send back to strict checks on contents of messages when sending messages between isolates that are not known to share the same code.

dart:mirrors

• Removed APIs [MirrorsUsed] and [Comment].

package:js

• Breaking changes to the preview feature @staticInterop:
  • Disallowed classes with this annotation from using external generative constructors. See 48730 and 49941 for more details.
  • Disallowed classes with this annotation’s external extension members from using type parameters.
  • Classes with this annotation should also have the @JS annotation.
  • Classes with this annotation can not be implemented by classes without this annotation.

dart2js

• dart2js no longer supports HTTP URIs as inputs.

Released in 2.18.0

Language

• Removed support for mixin of classes that don’t extend Object.

Libraries

dart:io

• Changed the uri property of RedirectException in dart:io to be nullable.
• Removed constants in dart:io networking APIs following the SCREAMING_CAPS convention.
• The Dart VM no longer automatically restores the initial terminal settings upon exit.

Tools

• Fully discontinued the .packages file.

Dart command line

• Removed the standalone dart2js and dartdevc tools.
• Removed the standalone dartanalyzer tool.

Released in 2.17.0

Libraries

dart:io

• Added new connectionFactory property to HttpClient.
• Added new keyLog property to HttpClient, which allows TLS keys to be logged for debugging purposes.
• Removed constants in dart:io following the SCREAMING_CAPS
• Added a new allowLegacyUnsafeRenegotiation property to SecurityContext, which allows TLS renegotiation for client secure sockets.

Tools

Dart command line

• Deprecated: Deprecated the standalone dart2js tool.
• Deprecated: Deprecated the standalone dartdevc tool.
• Removed: Removed the standalone dartdoc tool.

Released in 2.16.0

Libraries

dart:io

• On Windows, Directory.rename will no longer delete a directory if newPath specifies one. Instead, a FileSystemException will be thrown.
• Removed: Removed the Platform.packageRoot API.

dart:isolate

• Removed: Removed the Isolate.packageRoot API.

Tools

Dart command line

• Deprecated: Deprecated the standalone dartanalyzer tool.
• Deprecated: Deprecated the standalone dartdoc tool.
• Removed: Removed the deprecated standalone pub tool.

Released in 2.15.0

Libraries

dart:io

• Updated the SecurityContext class to set the minimum TLS protocol version to TLS1_2_VERSION (1.2) instead of TLS1_VERSION.

dart:web_sql

• Completely deleted the dart:web_sql library.

dart:html

• Removed window.openDatabase (related to dart:web_sql deletion above).

Tools

Dart command line

• Removed the standalone dart2native tool.
• Removed the standalone dartfmt tool.

Dart VM

• Removed support for dart-ext:-style native extensions
• Grouped isolates spawned via the Isolate.spawn() API to operate on the same managed heap, and therefore share various VM-internal data structures.

Released in 2.14.0

Libraries

dart:io

• The setter callbacks .authenticate and .authenticateProxy in HttpClient must now accept a nullable realm argument (for pre-migrated null safe code).

dart:typed_data

• Most types exposed by this library can no longer be extended, implemented or mixed-in.

Tools

Dart VM

• Expandos, and the object parameters of Dart_NewWeakPersistentHandle and Dart_NewFinalizableHandle, no longer accept Pointer and subtypes of Struct

Dart command line

• Deprecated the standalone dart2native tool
• Deprecated the standalone dartfmt tool.

dart2js

• dart2js no longer supports legacy browsers, because it emits ES6+ JavaScript by default.

Dart Dev Compiler (DDC)

• Changed subtyping relations of package:js classes to be more correct and consistent with Dart2JS.

Released in 2.13.0

Libraries

package:js

• No longer valid to use a String that matches an @Native annotation in an @JS() annotation for a non-anonymous JS interop class.

Released in 2.12.0

Language

• Null safety is now enabled by default in all code that has not opted out.
• Fixed an implementation bug where this would sometimes undergo type promotion in extensions.

Libraries

dart:ffi

• Deprecated invocations with a generic T of sizeOf<T>, Pointer<T>.elementAt(), Pointer<T extends Struct>.ref, and Pointer<T extends Struct>[]
• Deprecated allocate in package:ffi, as it will no longer be able to invoke sizeOf<T> generically.
• Deprecated subtypes of Struct without any native member.

Tools

Dart VM

• Dart_WeakPersistentHandle no longer auto-deletes itself when the referenced object is garbage collected to avoid race conditions.
• Renamed Dart_WeakPersistentHandleFinalizer to Dart_HandleFinalizer and removed its handle argument.

Pub

• The Dart SDK constraint is now required in pubspec.yaml.

Released in 2.10.0

Tools

Dart VM

• Renamed dart_api_dl.cc to dart_api_dl.c and changed to a pure C file.

Released in 2.9.0

Libraries

dart:convert

• When encoding a string containing unpaired surrogates as UTF-8, the unpaired surrogates will be encoded as replacement characters (U+FFFD).
• When decoding UTF-8, encoded surrogates will be treated as malformed input.
• Changed the number of replacement characters emitted for malformed input sequences to match the WHATWG encoding standard when decoding UTF-8 with allowMalformed: true.

dart:html

• CssClassSet.add() and CssClassSet.toggle now return false instead of null if the CssClassSet corresponds to multiple elements.

dart:mirrors

• Web compilers (dart2js and DDC) now produce a compile-time error if dart:mirrors is imported.

Tools

Dart VM

• When printing a string using the print function, the default implementation will print any unpaired surrogates in the string as replacement characters (U+FFFD).
• The Dart_StringToUTF8 function in the Dart API will convert unpaired surrogates into replacement characters.

Released in 2.8.1

Language

• Fixed an implementation bug where local variable inference would incorrectly use the promoted type of a type variable.
• Fixed an implementation bug surrounding the clauses implements Function, extends Function, or with Function no longer having an effect since Dart 2.0.0.

Libraries

dart:async

• Changed the return type of StreamSubscription.cancel() to Future<void>.
• Split the runZoned() function into two functions: runZoned() and runZonedGuarded(), where the latter has a required onError parameter, and the former has none.
• Errors passed to Completer.completeError(), Stream.addError(), Future.error(), etc. can no longer be null.
• Made stack traces non-null .

dart:core

• Three members on RuneIterator no longer return null when accessed before the first call to moveNext().
• The String.fromEnvironment() default value for defaultValue is now an empty string instead of null.
• The default value for int.fromEnvironment()’s defaultValue parameter is now zero.

dart:ffi

• Changed Pointer.asFunction() and DynamicLibrary.lookupFunction() to extension methods.

dart:io

• Changed the signature of HttpHeaders methods add() and set.
• The Socket class now throws a SocketException if the socket has been explicitly destroyed or upgraded to a secure socket upon setting or getting socket options.
• The Process class now throws a StateError if the process is detached (ProcessStartMode.detached and ProcessStartMode.detachedWithStdio) upon accessing the exitCode getter.
• The Process class now also throws when not connected to the child process’s stdio (ProcessStartMode.detached and ProcessStartMode.inheritStdio) upon accessing the stdin, stdout, and stderr getters.
• The dummy object returned if FileStat.stat() or FileStat.statSync() fail now contains Unix epoch timestamps instead of null for the accessed, changed, and modified getters.
• The HeaderValue class now parses more strictly in two invalid edge cases.

Tools

Dart Dev Compiler (DDC)

We fixed several inconsistencies between DDC and Dart2JS so that users less frequently encounter code that is accepted by one compiler but then fails in the other.

• Deleted the legacy (analyzer based) version of DDC.
• Functions passed to JavaScript using the recommended package:js interop specification must now be wrapped with a call to allowInterop.
• Constructors in @JS() classes must be marked with external.

dart2js

• Corresponding type parameter bounds now only need to be mutual subtypes rather than structurally equal up to renaming of bound type variables and equating all top types.
• Types are now normalized.
• Constructors in @JS() classes must be marked with external.
• Completely removed the --package-root flag, which was hidden and disabled in Dart 2.0.0.

Released in 2.7.1

• The Dart SDK for macOS is now only available for x64.

Released in 2.7.0

Language

• Static extension members are accessible when imported with a prefix.

Libraries

dart:io

• Added IOOverrides.serverSocketBind to aid in writing tests that wish to mock ServerSocket.bind.

Released in 2.6.0

Language

• Changed inference when using Null values in a FutureOr context. Namely, constraints of the forms similar to Null <: FutureOr<T> now yield Null as the solution for T.

Libraries

dart:ffi

• The API now makes use of static extension members.
• Removed memory management Pointer.allocate and Pointer.free.
• Pointer.offsetBy was removed, use cast and elementAt instead.

Released in 2.5.0

Libraries

• Various methods and properties across various core libraries, which used to declare a return type of List<int>, were updated to declare a return type of Uint8List.

dart:io

• The Cookie class’s constructor’s name and value optional positional parameters are now mandatory.
• The Cookie class’s name and value setters now validate that the strings are made from the allowed character set and are not null.

Tools

Pub

• Packages published to pub.dev can no longer contain git dependencies.

Released in 2.4.0

Language

• Covariance of type variables used in super-interfaces is now enforced.

Libraries

dart:isolate

• Isolate.resolvePackageUri will always throw an UnsupportedError when compiled with dart2js or DDC.

dart:async

• Fixed a bug in the StreamIterator class where await for allowed null as a stream.

Released in 2.2.0

Libraries

package:kernel

• The klass getter on the InstanceConstant class in the Kernel AST API has been renamed to classNode for consistency.
• Updated Link implementation to utilize true symbolic links instead of junctions on Windows.

Released in 2.1.1

Libraries

dart:io

• Added to a closed IOSink now throws a StateError.

Tools

Dart VM

• Fixed a soundness hole when using dart:mirrors to reflectively invoke a method in an incorrect way that violates its static types.

Released in 2.1.0

Language

• A number of static errors that should have been detected and reported were not supported in 2.0.0. These are reported now, which means existing incorrect code may show new errors:
  • Mixins must correctly override their superclasses.
  • Implicit type arguments in extends clauses must satisfy the class bounds.
  • Instance members should shadow prefixes.
  • Constructor invocations must use valid syntax, even with optional new.
  • Type arguments to generic typedefs must satisfy their bounds.
  • Classes can’t implement FutureOr.
  • Abstract methods may not unsoundly override a concrete method.
  • Constant constructors cannot redirect to non-constant constructors.
  • Setters with the same name as the enclosing class aren’t allowed.

Tools

dart2js

• Duplicate keys in a const map are not allowed and produce a compile-time error.

Released in 2.0.0

Language

• Replaced the unsound optional static type system with a sound static type system using type inference and runtime checks, formerly called strong mode.
• Functions marked async now run synchronously until the first await statement.

Libraries

• Renamed constants in the core libraries from SCREAMING_CAPS to lowerCamelCase.
• Added many new methods to core library classes that will need to be implemented if you implement the interfaces of these classes.
• dart:isolate and dart:mirrors are no longer supported when using Dart for the web.

Tools

Pub

• Replaced pub’s transformer-based build system with a new build system.