Breaking changes and deprecations

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.

Tentative
The following changes are expected to be included in the 3.4.0 stable release, but the final list will likely change before then. To reduce the potential impact of these changes, consider accounting for them before the 3.4.0 release.

• The pattern context type schema for cast patterns is now _ (the unknown type) instead of Object?.

• Experimental Removed: The waitFor function has been removed.

• These libraries are now marked as legacy and will see less support in the future. New projects should prefer to use package:web and dart:js_interop.

• This library is now marked as legacy and will see less support in the future. Usages should be migrated to dart:js_interop and dart:js_interop_unsafe. To learn more, check out /go/next-gen-js-interop.

• This library is now marked as legacy and will see less support in the future. Usages should be migrated to dart:js_interop and dart:js_interop_unsafe. To learn more, check out /go/next-gen-js-interop.

• Deprecated: The unmodifiable view classes for typed data are deprecated. Instead of using the constructors of these classes, use the new asUnmodifiableView methods on typed data lists.

• Experimental Deprecated: You should now specify a format to the --dump-info CLI option of either binary or json. The json format is deprecated and might be removed in a future Dart release.

• Experimental: Various dart compile wasm CLI arguments have been updated, removed, or replaced. To learn more, run dart compile wasm --verbose --help.

• Experimental Removed: The following experiments are now retired as they were released in Dart 3 and are no longer necessary with a language version of 3.0 or greater. Configuration of them should be removed from analysis options, CLI commands, and IDE configurations.

  • patterns
  • records
  • class-modifers
  • sealed-class

• An abstract getter is now considered promotable if there are no conflicting declarations.

• Experimental Deprecated: The waitFor function remains deprecated for another release and is set for removal in Dart 3.4.

• Deprecated: The elementAt pointer arithmetic methods on Pointer types are deprecated. Migrate to the - and + operators instead.
• Experimental Removed: The previously deprecated @FfiNative annotation has been removed. Usages should be updated to use the @Native annotation.

• Instead of using HttpRequest directly, it is now recommended to use package:http.

• Instead of using HttpClient directly, it is now recommended to use package:http.

• Experimental: JS types like JSAny have new compiler-specific representation types.
• Experimental: User-defined @staticInterop classes can no longer implement JSAny or JSObject. Usages should be migrated to JSObject.fromInteropObject or be defined as extension types.
• Experimental: JSArray and JSPromise now have generic parameters.
• Experimental: Various extension members were moved or renamed. To learn about the updated extensions, reference JSAnyUtilityExtension and JSAnyOperatorExtension.

• The unmodifiable view classes for typed data will be deprecated in Dart 3.4. Instead of using the constructors of these classes, use the new asUnmodifiableView methods on typed data lists.

• Experimental: All native wrapper classes are now marked base so that none of their subtypes can be implemented.

• The Invocation that is passed to noSuchMethod no longer has a minified memberName, even when compiled with --minify.

• Experimental: Disallow importing legacy JS interop libraries. Prefer using dart:js_interop and dart:js_interop_unsafe instead.

• Experimental: Invalid dart doc comment directives are now reported by the analyzer.

• Due to improvements in type promotion, the following analyzer diagnostics might trigger on existing code that previously passed analysis:

  • unnecessary_non_null_assertion
  • unnecessary_cast
  • invalid_null_aware_operator

• The iterable_contains_unrelated_type and list_remove_unrelated_type lints were removed. Consider migrating to the expanded collection_methods_unrelated_type lint.

• The following lints are removed due to no longer being necessary with sound null safety. You should remove configuration of them from your analysis_options.yaml files and any ignore comments.

  • always_require_non_null_named_parameters
  • avoid_returning_null
  • avoid_returning_null_for_future

• 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.

• Experimental Deprecated: The waitFor function.

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

• Deprecated: The Service.getIsolateID method.

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

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

• 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.

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

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

• 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
  dart

  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
      }
    }
  }

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

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

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

• 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.

• 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.

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

• Deprecated: Deprecated APIs.

• Removed: Removed the deprecated DeferredLibrary class.

• Language versioned: Changes to platform libraries.

• 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.

• Experimental Deprecated: The @FfiNative annotation is now deprecated. Usages should be updated to use the @Native annotation.

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

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

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

• 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.

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

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

• 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.

• 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.

• 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.

• Removed APIs [MirrorsUsed] and [Comment].

• 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 no longer supports HTTP URIs as inputs.

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

• 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.

• Fully discontinued the .packages file.

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

• 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.

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

• 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.

• Removed: Removed the Isolate.packageRoot API.

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

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

• Completely deleted the dart:web_sql library.

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

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

• 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.

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

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

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

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

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

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

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

• 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.

• 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.

• 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.

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

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

• 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.

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

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

• 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.

• 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.

• 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 .

• 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.

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

• 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.

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.

• 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.

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

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

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

• 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.

• 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.

• 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.

• 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.

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

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

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

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

• 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.

• Added to a closed IOSink now throws a StateError.

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

• 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.

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

• 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.

• 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.

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