CINXE.COM

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="x-ua-compatible" content="ie=edge"><meta name="viewport" content="width=device-width,initial-scale=1"><script>!function(e,t,a,n){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var g=t.getElementsByTagName(a)[0],m=t.createElement(a);m.async=!0,m.src="https://www.googletagmanager.com/gtm.js?id=GTM-5VSZM5J",g.parentNode.insertBefore(m,g)}(window,document,"script","dataLayer")</script><meta name="description" content="A deep dive into Dart language and library changes related to null safety."><title>Understanding null safety | Dart</title><link rel="icon" sizes="64x64" href="/assets/img/logo/dart-64.png" eleventy:ignore><link href="/assets/img/touch-icon-iphone.png" rel="apple-touch-icon" eleventy:ignore><link href="/assets/img/touch-icon-ipad.png" rel="apple-touch-icon" sizes="152x152" eleventy:ignore><link href="/assets/img/touch-icon-iphone-retina.png" rel="apple-touch-icon" sizes="180x180" eleventy:ignore><link href="/assets/img/touch-icon-ipad-retina.png" rel="apple-touch-icon" sizes="167x167" eleventy:ignore><meta name="twitter:card" content="summary"><meta name="twitter:site" content="@dart_lang"><meta name="twitter:title" content="Understanding null safety"><meta name="twitter:description" content="A deep dive into Dart language and library changes related to null safety."><meta property="og:title" content="Understanding null safety"><meta property="og:description" content="A deep dive into Dart language and library changes related to null safety."><meta property="og:url" content="/null-safety/understanding-null-safety/"><meta property="og:image" content="/assets/img/logo/dart-logo-for-shares.png?2" eleventy:ignore><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Display:wght@400&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0" rel="stylesheet"><link rel="stylesheet" href="/assets/css/main.css"><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min.js" integrity="sha512-3gJwYpMe3QewGELv8k/BX9vcqhryRdzRMxVfq6ngyWXwo03GFEzjsUm8Q7RZcHPHksttq7/GFoxjCVUjkjvPdw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/4.6.2/js/bootstrap.min.js" integrity="sha384-+sLIOodYLS7CIrQpBjl+C7nPvqq+FbNUBDunl/OZv93DB7Ln/533i8e/mZXLi/P+" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/js-cookie/3.0.5/js.cookie.min.js" integrity="sha512-nlp9/l96/EpjYBx7EP7pGASVXNe80hGhYAUrjeXnu/fyF5Py0/RXav4BBNs7n5Hx1WFhOEOWSAVjGeC3oKxDVQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="/assets/js/os-tabs.js"></script><script src="/assets/js/utilities.js"></script><script src="/assets/js/main.js"></script><script>!function(e,a,t,n,c,o,s){e.GoogleAnalyticsObject=c,e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},e[c].l=1*new Date,o=a.createElement(t),s=a.getElementsByTagName(t)[0],o.async=1,o.src="//www.google-analytics.com/analytics.js",s.parentNode.insertBefore(o,s)}(window,document,"script",0,"ga"),ga("create","UA-26406144-4","auto"),ga("send","pageview")</script></head><body class="default.html show_banner"><a id="skip" href="#site-content-title">Skip to main content</a><section id="cookie-notice"><div class="container">dart.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. <a href="https://policies.google.com/technologies/cookies" target="_blank" rel="noopener">Learn more</a>.<button id="cookie-consent" class="btn btn-primary">OK, got it</button></div></section><noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5VSZM5J" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript><header id="page-header" class="site-header"><nav id="mainnav" class="site-header"><div id="menu-toggle">menu</div><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart"></a><ul class="navbar"><li><a href="/overview" class="nav-link">Overview</a></li><li class="mainnav__get-started"><a href="/guides" class="nav-link">Docs</a></li><li><a href="/community" class="nav-link">Community</a></li><li><a href="/#try-dart" class="nav-link">Try Dart</a></li><li><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="searchfield"><form action="/search" class="site-header__search form-inline" id="cse-search-box"><input type="hidden" name="cx" value="011220921317074318178:_yy-tmb5t_i"> <input type="hidden" name="ie" value="UTF-8"> <input type="hidden" name="hl" value="en"> <input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-main" autocomplete="off" placeholder="Search" aria-label="Search"></form></li></ul></nav></header><div class="banner">Announcing Dart 3.5 and an updated Dart roadmap! <a href="https://medium.com/dartlang/dart-3-5-6ca36259fa2f" target="_blank">Learn more</a></div><div id="sidenav"><form action="/search/" class="site-header__search form-inline"><input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-side" autocomplete="off" placeholder="Search" aria-label="Search"></form><div class="site-sidebar"><ul class="navbar-nav"><li class="nav-item"><a href="/overview" class="nav-link">Overview</a></li><li class="nav-item"><a href="/community" class="nav-link">Community</a></li><li class="nav-item"><a href="https://dartpad.dev" class="nav-link">Try Dart</a></li><li class="nav-item"><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="nav-item"><a href="/guides" class="nav-link">Docs</a></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li></ul><ul class="nav flex-column"><li class="nav-item"><a class="nav-link active collapsible" data-toggle="collapse" href="#sidenav-1" role="button" aria-expanded="true" aria-controls="sidenav-1">Language</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-1"><li class="nav-item"><a class="nav-link" href="/language">Introduction</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-2" href="#sidenav-1-2" role="button" aria-expanded="false" aria-controls="sidenav-1-2">Syntax basics</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-2"><li class="nav-item"><a class="nav-link" href="/language/variables">Variables</a></li><li class="nav-item"><a class="nav-link" href="/language/operators">Operators</a></li><li class="nav-item"><a class="nav-link" href="/language/comments">Comments</a></li><li class="nav-item"><a class="nav-link" href="/language/metadata">Metadata</a></li><li class="nav-item"><a class="nav-link" href="/language/libraries">Libraries & imports</a></li><li class="nav-item"><a class="nav-link" href="/language/keywords">Keywords</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-3" href="#sidenav-1-3" role="button" aria-expanded="false" aria-controls="sidenav-1-3">Types</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-3"><li class="nav-item"><a class="nav-link" href="/language/built-in-types">Built-in types</a></li><li class="nav-item"><a class="nav-link" href="/language/records">Records</a></li><li class="nav-item"><a class="nav-link" href="/language/collections">Collections</a></li><li class="nav-item"><a class="nav-link" href="/language/generics">Generics</a></li><li class="nav-item"><a class="nav-link" href="/language/typedefs">Typedefs</a></li><li class="nav-item"><a class="nav-link" href="/language/type-system">Type system</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-4" href="#sidenav-1-4" role="button" aria-expanded="false" aria-controls="sidenav-1-4">Patterns</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-4"><li class="nav-item"><a class="nav-link" href="/language/patterns">Overview & usage</a></li><li class="nav-item"><a class="nav-link" href="/language/pattern-types">Pattern types</a></li><li class="nav-item"><a class="nav-link" href="https://codelabs.developers.google.com/codelabs/dart-patterns-records" target="_blank" rel="noopener">Applied tutorial</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/language/functions">Functions</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-6" href="#sidenav-1-6" role="button" aria-expanded="false" aria-controls="sidenav-1-6">Control flow</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-6"><li class="nav-item"><a class="nav-link" href="/language/loops">Loops</a></li><li class="nav-item"><a class="nav-link" href="/language/branches">Branches</a></li><li class="nav-item"><a class="nav-link" href="/language/error-handling">Error handling</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-7" href="#sidenav-1-7" role="button" aria-expanded="false" aria-controls="sidenav-1-7">Classes & objects</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-7"><li class="nav-item"><a class="nav-link" href="/language/classes">Classes</a></li><li class="nav-item"><a class="nav-link" href="/language/constructors">Constructors</a></li><li class="nav-item"><a class="nav-link" href="/language/methods">Methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extend">Extend a class</a></li><li class="nav-item"><a class="nav-link" href="/language/mixins">Mixins</a></li><li class="nav-item"><a class="nav-link" href="/language/enums">Enums</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-methods">Extension methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-types">Extension types</a></li><li class="nav-item"><a class="nav-link" href="/language/callable-objects">Callable objects</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-8" href="#sidenav-1-8" role="button" aria-expanded="false" aria-controls="sidenav-1-8">Class modifiers</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-8"><li class="nav-item"><a class="nav-link" href="/language/class-modifiers">Overview & usage</a></li><li class="nav-item"><a class="nav-link" href="/language/class-modifiers-for-apis">Class modifiers for API maintainers</a></li><li class="nav-item"><a class="nav-link" href="/language/modifier-reference">Reference</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-9" href="#sidenav-1-9" role="button" aria-expanded="false" aria-controls="sidenav-1-9">Concurrency</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-9"><li class="nav-item"><a class="nav-link" href="/language/concurrency">Overview</a></li><li class="nav-item"><a class="nav-link" href="/language/async">Asynchronous support</a></li><li class="nav-item"><a class="nav-link" href="/language/isolates">Isolates</a></li></ul></li><li class="nav-item"><a class="nav-link active collapsible" data-toggle="collapse" data-target="#sidenav-1-10" href="#sidenav-1-10" role="button" aria-expanded="true" aria-controls="sidenav-1-10">Null safety</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-1-10"><li class="nav-item"><a class="nav-link" href="/null-safety">Sound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/migration-guide">Migrating to null safety</a></li><li class="nav-item"><a class="nav-link active" href="/null-safety/understanding-null-safety">Understanding null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/unsound-null-safety">Unsound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/faq">FAQ</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-2" role="button" aria-expanded="false" aria-controls="sidenav-2">Core libraries</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2"><li class="nav-item"><a class="nav-link" href="/libraries">Overview</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-core">dart:core</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-async">dart:async</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-math">dart:math</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-convert">dart:convert</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-io">dart:io</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-html">dart:html</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/libraries/collections/iterables">Iterable collections</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-2-10" href="#sidenav-2-10" role="button" aria-expanded="false" aria-controls="sidenav-2-10">Asynchronous programming</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2-10"><li class="nav-item"><a class="nav-link" href="/libraries/async/async-await">Tutorial</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/futures-error-handling">Futures and error handling</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/using-streams">Using streams</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/creating-streams">Creating streams</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-3" role="button" aria-expanded="false" aria-controls="sidenav-3">Effective Dart</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-3"><li class="nav-item"><a class="nav-link" href="/effective-dart">Overview</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/style">Style</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/documentation">Documentation</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/design">Design</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-4" role="button" aria-expanded="false" aria-controls="sidenav-4">Packages</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-4"><li class="nav-item"><a class="nav-link" href="/tools/pub/packages">How to use packages</a></li><li class="nav-item"><a class="nav-link" href="/resources/useful-packages">Commonly used packages</a></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/create-packages">Creating packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/publishing">Publishing packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/writing-package-pages">Writing package pages</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-4-6" href="#sidenav-4-6" role="button" aria-expanded="false" aria-controls="sidenav-4-6">Package reference</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-4-6"><li class="nav-item"><a class="nav-link" href="/tools/pub/dependencies">Dependencies</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/package-layout">Package layout conventions</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/environment-variables">Pub environment variables</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/pubspec">Pubspec file</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/troubleshoot">Troubleshooting pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/verified-publishers">Verified publishers</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/security-advisories">Security advisories</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/versioning">Versioning</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/custom-package-repositories">Custom package repositories</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/private-files">What not to commit</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-5" role="button" aria-expanded="false" aria-controls="sidenav-5">Development</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5"><li class="nav-item"><a class="nav-link" href="/guides/json">JSON</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/numbers">Number representation</a></li><li class="nav-item"><a class="nav-link" href="/resources/google-apis">Google APIs</a></li><li class="nav-item"><a class="nav-link" href="/multiplatform-apps">Multi-platform apps</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-5-5" href="#sidenav-5-5" role="button" aria-expanded="false" aria-controls="sidenav-5-5">Command-line & server apps</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5-5"><li class="nav-item"><a class="nav-link" href="/server">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/get-started">Get started</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/cmdline">Write command-line apps</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/fetch-data">Fetch data from the internet</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/httpserver">Write HTTP servers</a></li><li class="nav-item"><a class="nav-link" href="/server/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/server/google-cloud">Google Cloud</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-5-6" href="#sidenav-5-6" role="button" aria-expanded="false" aria-controls="sidenav-5-6">Web apps</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5-6"><li class="nav-item"><a class="nav-link" href="/web">Overview</a></li><li class="nav-item"><a class="nav-link" href="/web/get-started">Get started</a></li><li class="nav-item"><a class="nav-link" href="/web/deployment">Deployment</a></li><li class="nav-item"><a class="nav-link" href="/web/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/web/wasm">Wasm compilation</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/environment-declarations">Environment declarations</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-6" role="button" aria-expanded="false" aria-controls="sidenav-6">Interoperability</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6"><li class="nav-item"><a class="nav-link" href="/interop/c-interop">C interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/objective-c-interop">Objective-C & Swift interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/java-interop">Java & Kotlin interop</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-6-4" href="#sidenav-6-4" role="button" aria-expanded="false" aria-controls="sidenav-6-4">JavaScript interop</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6-4"><li class="nav-item"><a class="nav-link" href="/interop/js-interop">Overview</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/js-types">JS types</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/tutorials">Tutorials</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/past-js-interop">Past JS interop</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/interop/js-interop/package-web">Web interop</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-7" role="button" aria-expanded="false" aria-controls="sidenav-7">Tools & techniques</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7"><li class="nav-item"><a class="nav-link" href="/tools">Overview</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2" href="#sidenav-7-2" role="button" aria-expanded="false" aria-controls="sidenav-7-2">Editors & debuggers</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2"><li class="nav-item"><a class="nav-link" href="/tools/jetbrains-plugin">IntelliJ & Android Studio</a></li><li class="nav-item"><a class="nav-link" href="/tools/vs-code">VS Code</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-devtools">Dart DevTools</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2-4" href="#sidenav-7-2-4" role="button" aria-expanded="false" aria-controls="sidenav-7-2-4">DartPad</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2-4"><li class="nav-item"><a class="nav-link" href="/tools/dartpad">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartpad/troubleshoot">Troubleshooting DartPad</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-3" href="#sidenav-7-3" role="button" aria-expanded="false" aria-controls="sidenav-7-3">Command-line tools</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-3"><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-1" href="#sidenav-7-3-1" role="button" aria-expanded="true" aria-controls="sidenav-7-3-1">Dart SDK</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-1"><li class="nav-item"><a class="nav-link" href="/tools/sdk">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-tool">dart</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-analyze">dart analyze</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-compile">dart compile</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-create">dart create</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-doc">dart doc</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-fix">dart fix</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-format">dart format</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-info">dart info</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/cmd">dart pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-run">dart run</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-test">dart test</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartaotruntime">dartaotruntime</a></li><li class="nav-item"><a class="nav-link" href="/tools/experiment-flags">Experiment flags</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-2" href="#sidenav-7-3-2" role="button" aria-expanded="true" aria-controls="sidenav-7-3-2">Other command-line tools</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-2"><li class="nav-item"><a class="nav-link" href="/tools/build_runner">build_runner</a></li><li class="nav-item"><a class="nav-link" href="/tools/webdev">webdev</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-4" href="#sidenav-7-4" role="button" aria-expanded="false" aria-controls="sidenav-7-4">Static analysis</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-4"><li class="nav-item"><a class="nav-link" href="/tools/analysis">Customizing static analysis</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/sound-problems">Fixing common type problems</a></li><li class="nav-item"><a class="nav-link" href="/tools/non-promotion-reasons">Fixing type promotion failures</a></li><li class="nav-item"><a class="nav-link" href="/tools/linter-rules">Linter rules</a></li><li class="nav-item"><a class="nav-link" href="/tools/diagnostic-messages">Diagnostic messages</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-5" href="#sidenav-7-5" role="button" aria-expanded="false" aria-controls="sidenav-7-5">Testing & optimization</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-5"><li class="nav-item"><a class="nav-link" href="/guides/testing">Testing</a></li><li class="nav-item"><a class="nav-link" href="/web/debugging">Debugging web apps</a></li></ul></li></ul></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-9" role="button" aria-expanded="false" aria-controls="sidenav-9">Resources</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9"><li class="nav-item"><a class="nav-link" href="/resources/dart-cheatsheet">Language cheatsheet</a></li><li class="nav-item"><a class="nav-link" href="/resources/breaking-changes">Breaking changes</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/evolution">Language evolution</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/spec">Language specification</a></li><li class="nav-item"><a class="nav-link" href="/resources/dart-3-migration">Dart 3 migration guide</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-9-6" href="#sidenav-9-6" role="button" aria-expanded="false" aria-controls="sidenav-9-6">Coming from ...</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9-6"><li class="nav-item"><a class="nav-link" href="/resources/coming-from/js-to-dart">JavaScript to Dart</a></li><li class="nav-item"><a class="nav-link" href="/resources/coming-from/swift-to-dart">Swift to Dart</a></li></ul></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/resources/faq">FAQ</a></li><li class="nav-item"><a class="nav-link" href="/resources/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link" href="/resources/books">Books</a></li><li class="nav-item"><a class="nav-link" href="/resources/videos">Videos</a></li><li class="nav-item"><a class="nav-link" href="/tutorials">Tutorials</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" href="#sidenav-10" role="button" aria-expanded="true" aria-controls="sidenav-10">Related sites</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-10"><li class="nav-item"><a class="nav-link" href="https://api.dart.dev" target="_blank" rel="noopener">API reference</a></li><li class="nav-item"><a class="nav-link" href="https://medium.com/dartlang" target="_blank" rel="noopener">Blog</a></li><li class="nav-item"><a class="nav-link" href="https://dartpad.dev" target="_blank" rel="noopener">DartPad (online editor)</a></li><li class="nav-item"><a class="nav-link" href="https://flutter.dev" target="_blank" rel="noopener">Flutter</a></li><li class="nav-item"><a class="nav-link" href="https://pub.dev" target="_blank" rel="noopener">Package site</a></li></ul></li></ul></div></div><main id="page-content"><div id="site-toc--side" class="site-toc"><header class="site-toc__title">Contents</header><ul class="section-nav"><li class="toc-entry nav-item"><a class="nav-link" href="#nullability-in-the-type-system">Nullability in the type system</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#non-nullable-and-nullable-types">Non-nullable and nullable types</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#using-nullable-types">Using nullable types</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#top-and-bottom">Top and bottom</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#ensuring-correctness">Ensuring correctness</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#invalid-returns">Invalid returns</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#uninitialized-variables">Uninitialized variables</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#flow-analysis">Flow analysis</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#reachability-analysis">Reachability analysis</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#never-for-unreachable-code">Never for unreachable code</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#definite-assignment-analysis">Definite assignment analysis</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#type-promotion-on-null-checks">Type promotion on null checks</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#unnecessary-code-warnings">Unnecessary code warnings</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#working-with-nullable-types">Working with nullable types</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#smarter-null-aware-methods">Smarter null-aware methods</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#non-null-assertion-operator">Non-null assertion operator</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#late-variables">Late variables</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#lazy-initialization">Lazy initialization</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#late-final-variables">Late final variables</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#required-named-parameters">Required named parameters</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#abstract-fields">Abstract fields</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#working-with-nullable-fields">Working with nullable fields</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#nullability-and-generics">Nullability and generics</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#core-library-changes">Core library changes</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#the-map-index-operator-is-nullable">The Map index operator is nullable</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#no-unnamed-list-constructor">No unnamed List constructor</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#cannot-set-a-larger-length-on-non-nullable-lists">Cannot set a larger length on non-nullable lists</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#cannot-access-iterator-current-before-or-after-iteration">Cannot access Iterator.current before or after iteration</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#summary">Summary</a></li></ul></div><article><div class="content"><div id="site-content-title"><h1>Understanding null safety</h1></div><div id="site-toc--inline" class="site-toc toc-collapsible toc-collapsed"><header class="site-toc__title">Contents keyboard_arrow_down keyboard_arrow_up</header><ul class="section-nav"><li class="toc-entry"><a href="#nullability-in-the-type-system">Nullability in the type system</a><ul><li class="toc-entry"><a href="#non-nullable-and-nullable-types">Non-nullable and nullable types</a></li><li class="toc-entry"><a href="#using-nullable-types">Using nullable types</a></li><li class="toc-entry"><a href="#top-and-bottom">Top and bottom</a></li></ul></li><li class="toc-entry"><a href="#ensuring-correctness">Ensuring correctness</a><ul><li class="toc-entry"><a href="#invalid-returns">Invalid returns</a></li><li class="toc-entry"><a href="#uninitialized-variables">Uninitialized variables</a></li></ul></li><li class="toc-entry"><a href="#flow-analysis">Flow analysis</a><ul><li class="toc-entry"><a href="#reachability-analysis">Reachability analysis</a></li><li class="toc-entry"><a href="#never-for-unreachable-code">Never for unreachable code</a></li><li class="toc-entry"><a href="#definite-assignment-analysis">Definite assignment analysis</a></li><li class="toc-entry"><a href="#type-promotion-on-null-checks">Type promotion on null checks</a></li><li class="toc-entry"><a href="#unnecessary-code-warnings">Unnecessary code warnings</a></li></ul></li><li class="toc-entry"><a href="#working-with-nullable-types">Working with nullable types</a><ul><li class="toc-entry"><a href="#smarter-null-aware-methods">Smarter null-aware methods</a></li><li class="toc-entry"><a href="#non-null-assertion-operator">Non-null assertion operator</a></li><li class="toc-entry"><a href="#late-variables">Late variables</a></li><li class="toc-entry"><a href="#lazy-initialization">Lazy initialization</a></li><li class="toc-entry"><a href="#late-final-variables">Late final variables</a></li><li class="toc-entry"><a href="#required-named-parameters">Required named parameters</a></li><li class="toc-entry"><a href="#abstract-fields">Abstract fields</a></li><li class="toc-entry"><a href="#working-with-nullable-fields">Working with nullable fields</a></li><li class="toc-entry"><a href="#nullability-and-generics">Nullability and generics</a></li></ul></li><li class="toc-entry"><a href="#core-library-changes">Core library changes</a><ul><li class="toc-entry"><a href="#the-map-index-operator-is-nullable">The Map index operator is nullable</a></li><li class="toc-entry"><a href="#no-unnamed-list-constructor">No unnamed List constructor</a></li><li class="toc-entry"><a href="#cannot-set-a-larger-length-on-non-nullable-lists">Cannot set a larger length on non-nullable lists</a></li><li class="toc-entry"><a href="#cannot-access-iterator-current-before-or-after-iteration">Cannot access Iterator.current before or after iteration</a></li></ul></li><li class="toc-entry"><a href="#summary">Summary</a></li></ul>more_horiz</div>Written by Bob Nystrom July 2020Null safety is the largest change we've made to Dart since we replaced the original unsound optional type system with <a href="/language/type-system">a sound static type system</a> in Dart 2.0. When Dart first launched, compile-time null safety was a rare feature needing a long introduction. Today, Kotlin, Swift, Rust, and other languages all have their own answers to what has become a very <a href="https://www.infoq.com/presentations/Null-References-The-Billion-Dollar-Mistake-Tony-Hoare/">familiar problem.</a> Here is an example:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Without null safety: bool isEmpty(String string) => string.length == 0; void main() { isEmpty(null); }</code></pre></div></div>If you run this Dart program without null safety, it throws a <code>NoSuchMethodError</code> exception on the call to <code>.length</code>. The <code>null</code> value is an instance of the <code>Null</code> class, and <code>Null</code> has no "length" getter. Runtime failures suck. This is especially true in a language like Dart that is designed to run on an end-user's device. If a server application fails, you can often restart it before anyone notices. But when a Flutter app crashes on a user's phone, they are not happy. When your users aren't happy, you aren't happy.Developers like statically-typed languages like Dart because they enable the type checker to find mistakes in code at compile time, usually right in the IDE. The sooner you find a bug, the sooner you can fix it. When language designers talk about "fixing null reference errors", they mean enriching the static type checker so that the language can detect mistakes like the above attempt to call <code>.length</code> on a value that might be <code>null</code>.There is no one true solution to this problem. Rust and Kotlin both have their own approach that makes sense in the context of those languages. This doc walks through all the details of our answer for Dart. It includes changes to the static type system and a suite of other modifications and new language features to let you not only write null-safe code but hopefully to enjoy doing so.This document is long. If you want something shorter that covers just what you need to know to get up and running, start with the <a href="/null-safety">overview</a>. When you are ready for a deeper understanding and have the time, come back here so you can understand how the language handles <code>null</code>, why we designed it that way, and how to write idiomatic, modern, null-safe Dart. (Spoiler alert: it ends up surprisingly close to how you write Dart today.)The various ways a language can tackle null reference errors each have their pros and cons. These principles guided the choices we made:<ul><li>Code should be safe by default. If you write new Dart code and don't use any explicitly unsafe features, it never throws a null reference error at runtime. All possible null reference errors are caught statically. If you want to defer some of that checking to runtime to get greater flexibility, you can, but you have to choose that by using some feature that is textually visible in the code.In other words, we aren't giving you a life jacket and leaving it up to you to remember to put it on every time you go out on the water. Instead, we give you a boat that doesn't sink. You stay dry unless you jump overboard.</li><li>Null-safe code should be easy to write. Most existing Dart code is dynamically correct and does not throw null reference errors. You like your Dart program the way it looks now, and we want you to be able to keep writing code that way. Safety shouldn't require sacrificing usability, paying penance to the type checker, or having to significantly change the way you think.</li><li>The resulting null-safe code should be fully sound. "Soundness" in the context of static checking means different things to different people. For us, in the context of null safety, that means that if an expression has a static type that does not permit <code>null</code>, then no possible execution of that expression can ever evaluate to <code>null</code>. The language provides this guarantee mostly through static checks, but there can be some runtime checks involved too. (Though, note the first principle: any place where those runtime checks happen will be your choice.)Soundness is important for user confidence. A boat that mostly stays afloat is not one you're enthused to brave the open seas on. But it's also important for our intrepid compiler hackers. When the language makes hard guarantees about semantic properties of a program, it means that the compiler can perform optimizations that assume those properties are true. When it comes to <code>null</code>, it means we can generate smaller code that eliminates unneeded <code>null</code> checks, and faster code that doesn't need to verify a receiver is non-<code>null</code> before calling methods on it.One caveat: We only guarantee soundness in Dart programs that are fully null safe. Dart supports programs that contain a mixture of newer null-safe code and older legacy code. In these mixed-version programs, null reference errors may still occur. In a mixed-version program, you get all of the static safety benefits in the portions that are null safe, but you don't get full runtime soundness until the entire application is null safe.</li></ul>Note that eliminating <code>null</code> is not a goal. There's nothing wrong with <code>null</code>. On the contrary, it's really useful to be able to represent the absence of a value. Building support for a special "absent" value directly into the language makes working with absence flexible and usable. It underpins optional parameters, the handy <code>?.</code> null-aware operator, and default initialization. It is not <code>null</code> that is bad, it is having <code>null</code> go where you don't expect it that causes problems.Thus with null safety, our goal is to give you control and insight into where <code>null</code> can flow through your program and certainty that it can't flow somewhere that would cause a crash.<div class="header-wrapper"><h2 id="nullability-in-the-type-system">Nullability in the type system</h2><a class="heading-link" href="#nullability-in-the-type-system" aria-label="Link to 'Nullability in the type system' section">#</a></div>Null safety begins in the static type system because everything else rests upon that. Your Dart program has a whole universe of types in it: primitive types like <code>int</code> and <code>String</code>, collection types like <code>List</code>, and all of the classes and types you and the packages you use define. Before null safety, the static type system allowed the value <code>null</code> to flow into expressions of any of those types.In type theory lingo, the <code>Null</code> type was treated as a subtype of all types:<img src="/assets/img/null-safety/understanding-null-safety/hierarchy-before.png" alt="Null Safety Hierarchy Before" width="335">The set of operations鈥攇etters, setters, methods, and operators鈥攁llowed on some expressions are defined by its type. If the type is <code>List</code>, you can call <code>.add()</code> or <code>[]</code> on it. If it's <code>int</code>, you can call <code>+</code>. But the <code>null</code> value doesn't define any of those methods. Allowing <code>null</code> to flow into an expression of some other type means any of those operations can fail. This is really the crux of null reference errors鈥攅very failure comes from trying to look up a method or property on <code>null</code> that it doesn't have.<div class="header-wrapper"><h3 id="non-nullable-and-nullable-types">Non-nullable and nullable types</h3><a class="heading-link" href="#non-nullable-and-nullable-types" aria-label="Link to 'Non-nullable and nullable types' section">#</a></div>Null safety eliminates that problem at the root by changing the type hierarchy. The <code>Null</code> type still exists, but it's no longer a subtype of all types. Instead, the type hierarchy looks like this:<img src="/assets/img/null-safety/understanding-null-safety/hierarchy-after.png" alt="Null Safety Hierarchy After" width="344">Since <code>Null</code> is no longer a subtype, no type except the special <code>Null</code> class permits the value <code>null</code>. We've made all types non-nullable by default. If you have a variable of type <code>String</code>, it will always contain a string. There, we've fixed all null reference errors.If we didn't think <code>null</code> was useful at all, we could stop here. But <code>null</code> is useful, so we still need a way to handle it. Optional parameters are a good illustrative case. Consider this null-safe Dart code:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: void makeCoffee(String coffee, [String? dairy]) { if (dairy != null) { print('$coffee with $dairy'); } else { print('Black $coffee'); } }</code></pre></div></div>Here, we want to allow the <code>dairy</code> parameter to accept any string, or the value <code>null</code>, but nothing else. To express that, we give <code>dairy</code> a nullable type by slapping <code>?</code> at the end of the underlying base type <code>String</code>. Under the hood, this is essentially defining a <a href="https://en.wikipedia.org/wiki/Union_type">union</a> of the underlying type and the <code>Null</code> type. So <code>String?</code> would be a shorthand for <code>String|Null</code> if Dart had full-featured union types.<div class="header-wrapper"><h3 id="using-nullable-types">Using nullable types</h3><a class="heading-link" href="#using-nullable-types" aria-label="Link to 'Using nullable types' section">#</a></div>If you have an expression with a nullable type, what can you do with the result? Since our principle is safe by default, the answer is not much. We can't let you call methods of the underlying type on it because those might fail if the value is <code>null</code>:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Hypothetical unsound null safety: void bad(String? maybeString) { print(maybeString.length); } void main() { bad(null); }</code></pre></div></div>This would crash if we let you run it. The only methods and properties we can safely let you access are ones defined by both the underlying type and the <code>Null</code> class. That's just <code>toString()</code>, <code>==</code>, and <code>hashCode</code>. So you can use nullable types as map keys, store them in sets, compare them to other values, and use them in string interpolation, but that's about it.How do they interact with non-nullable types? It's always safe to pass a non-nullable type to something expecting a nullable type. If a function accepts <code>String?</code> then passing a <code>String</code> is allowed because it won't cause any problems. We model this by making every nullable type a supertype of its underlying type. You can also safely pass <code>null</code> to something expecting a nullable type, so <code>Null</code> is also a subtype of every nullable type:<img src="/assets/img/null-safety/understanding-null-safety/nullable-hierarchy.png" alt="Nullable" width="235">But going the other direction and passing a nullable type to something expecting the underlying non-nullable type is unsafe. Code that expects a <code>String</code> may call <code>String</code> methods on the value. If you pass a <code>String?</code> to it, <code>null</code> could flow in and that could fail:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Hypothetical unsound null safety: void requireStringNotNull(String definitelyString) { print(definitelyString.length); } void main() { String? maybeString = null; // Or not! requireStringNotNull(maybeString); }</code></pre></div></div>This program is not safe and we shouldn't allow it. However, Dart has always had this thing called implicit downcasts. If you, for example, pass a value of type <code>Object</code> to a function expecting a <code>String</code>, the type checker allows it:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Without null safety: void requireStringNotObject(String definitelyString) { print(definitelyString.length); } void main() { Object maybeString = 'it is'; requireStringNotObject(maybeString); }</code></pre></div></div>To maintain soundness, the compiler silently inserts an <code>as String</code> cast on the argument to <code>requireStringNotObject()</code>. That cast could fail and throw an exception at runtime, but at compile time, Dart says this is OK. Since non-nullable types are modeled as subtypes of nullable types, implicit downcasts would let you pass a <code>String?</code> to something expecting a <code>String</code>. Allowing that would violate our goal of being safe by default. So with null safety we are removing implicit downcasts entirely.This makes the call to <code>requireStringNotNull()</code> produce a compile error, which is what you want. But it also means all implicit downcasts become compile errors, including the call to <code>requireStringNotObject()</code>. You'll have to add the explicit downcast yourself:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: void requireStringNotObject(String definitelyString) { print(definitelyString.length); } void main() { Object maybeString = 'it is'; requireStringNotObject(maybeString as String); }</code></pre></div></div>We think this is an overall good change. Our impression is that most users never liked implicit downcasts. In particular, you may have been burned by this before:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Without null safety: List<int> filterEvens(List<int> ints) { return ints.where((n) => n.isEven); }</code></pre></div></div>Spot the bug? The <code>.where()</code> method is lazy, so it returns an <code>Iterable</code>, not a <code>List</code>. This program compiles but then throws an exception at runtime when it tries to cast that <code>Iterable</code> to the <code>List</code> type that <code>filterEvens</code> declares it returns. With the removal of implicit downcasts, this becomes a compile error.Where were we? Right, OK, so it's as if we've taken the universe of types in your program and split them into two halves:<img src="/assets/img/null-safety/understanding-null-safety/bifurcate.png" alt="Nullable and Non-Nullable types" width="668">There is a region of non-nullable types. Those types let you access all of the interesting methods, but can never ever contain <code>null</code>. And then there is a parallel family of all of the corresponding nullable types. Those permit <code>null</code>, but you can't do much with them. We let values flow from the non-nullable side to the nullable side because doing so is safe, but not the other direction.That seems like nullable types are basically useless. They have no methods and you can't get away from them. Don't worry, we have a whole suite of features to help you move values from the nullable half over to the other side that we will get to soon.<div class="header-wrapper"><h3 id="top-and-bottom">Top and bottom</h3><a class="heading-link" href="#top-and-bottom" aria-label="Link to 'Top and bottom' section">#</a></div>This section is a little esoteric. You can mostly skip it, except for two bullets at the very end, unless you're into type system stuff. Imagine all the types in your program with edges between ones that are subtypes and supertypes of each other. If you were to draw it, like the diagrams in this doc, it would form a huge directed graph with supertypes like <code>Object</code> near the top and leaf classes like your own types near the bottom.If that directed graph comes to a point at the top where there is a single type that is the supertype (directly or indirectly), that type is called the top type. Likewise, if there is a weird type at that bottom that is a subtype of every type, you have a bottom type. (In this case, your directed graph is a <a href="https://en.wikipedia.org/wiki/Lattice_(order)">lattice.</a>)It's convenient if your type system has a top and bottom type, because it means that type-level operations like least upper bound (which type inference uses to figure out the type of a conditional expression based on the types of its two branches) can always produce a type. Before null safety, <code>Object</code> was Dart's top type and <code>Null</code> was its bottom type.Since <code>Object</code> is non-nullable now, it is no longer a top type. <code>Null</code> is not a subtype of it. Dart has no named top type. If you need a top type, you want <code>Object?</code>. Likewise, <code>Null</code> is no longer the bottom type. If it was, everything would still be nullable. Instead, we've added a new bottom type named <code>Never</code>:<img src="/assets/img/null-safety/understanding-null-safety/top-and-bottom.png" alt="Top and Bottom" width="360">In practice, this means:<ul><li>If you want to indicate that you allow a value of any type, use <code>Object?</code> instead of <code>Object</code>. In fact, it becomes pretty unusual to use <code>Object</code> since that type means "could be any possible value except this one weirdly prohibited value <code>null</code>".</li><li>On the rare occasion that you need a bottom type, use <code>Never</code> instead of <code>Null</code>. This is particularly useful to indicate a function never returns to <a href="#never-for-unreachable-code">help reachability analysis</a>. If you don't know if you need a bottom type, you probably don't.</li></ul><div class="header-wrapper"><h2 id="ensuring-correctness">Ensuring correctness</h2><a class="heading-link" href="#ensuring-correctness" aria-label="Link to 'Ensuring correctness' section">#</a></div>We divided the universe of types into nullable and non-nullable halves. In order to maintain soundness and our principle that you can never get a null reference error at runtime unless you ask for it, we need to guarantee that <code>null</code> never appears in any type on the non-nullable side.Getting rid of implicit downcasts and removing <code>Null</code> as a bottom type covers all of the main places that types flow through a program across assignments and from arguments into parameters on function calls. The main remaining places where <code>null</code> can sneak in are when a variable first comes into being and when you leave a function. So there are some additional compile errors:<div class="header-wrapper"><h3 id="invalid-returns">Invalid returns</h3><a class="heading-link" href="#invalid-returns" aria-label="Link to 'Invalid returns' section">#</a></div>If a function has a non-nullable return type, then every path through the function must reach a <code>return</code> statement that returns a value. Before null safety, Dart was pretty lax about missing returns. For example:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Without null safety: String missingReturn() { // No return. }</code></pre></div></div>If you analyzed this, you got a gentle hint that maybe you forgot a return, but if not, no big deal. That's because if execution reaches the end of a function body then Dart implicitly returns <code>null</code>. Since every type is nullable, technically this function is safe, even though it's probably not what you want.With sound non-nullable types, this program is flat out wrong and unsafe. Under null safety, you get a compile error if a function with a non-nullable return type doesn't reliably return a value. By "reliably", I mean that the language analyzes all of the control flow paths through the function. As long as they all return something, it is satisfied. The analysis is pretty smart, so even this function is OK:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: String alwaysReturns(int n) { if (n == 0) { return 'zero'; } else if (n < 0) { throw ArgumentError('Negative values not allowed.'); } else { if (n > 1000) { return 'big'; } else { return n.toString(); } } }</code></pre></div></div>We'll dive more deeply into the new flow analysis in the next section.<div class="header-wrapper"><h3 id="uninitialized-variables">Uninitialized variables</h3><a class="heading-link" href="#uninitialized-variables" aria-label="Link to 'Uninitialized variables' section">#</a></div>When you declare a variable, if you don't give it an explicit initializer, Dart default initializes the variable with <code>null</code>. That's convenient, but obviously totally unsafe if the variable's type is non-nullable. So we have to tighten things up for non-nullable variables:<ul><li>Top level variable and static field declarations must have an initializer. Since these can be accessed and assigned from anywhere in the program, it's impossible for the compiler to guarantee that the variable has been given a value before it gets used. The only safe option is to require the declaration itself to have an initializing expression that produces a value of the right type:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: int topLevel = 0; class SomeClass { static int staticField = 0; }</code></pre></div></div></li><li>Instance fields must either have an initializer at the declaration, use an initializing formal, or be initialized in the constructor's initialization list. That's a lot of jargon. Here are the examples:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class SomeClass { int atDeclaration = 0; int initializingFormal; int initializationList; SomeClass(this.initializingFormal) : initializationList = 0; }</code></pre></div></div>In other words, as long as the field has a value before you reach the constructor body, you're good.</li><li>Local variables are the most flexible case. A non-nullable local variable doesn't need to have an initializer. This is perfectly fine:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: int tracingFibonacci(int n) { int result; if (n < 2) { result = n; } else { result = tracingFibonacci(n - 2) + tracingFibonacci(n - 1); } print(result); return result; }</code></pre></div></div>The rule is only that a local variable must be definitely assigned before it is used. We get to rely on the new flow analysis I alluded to for this as well. As long as every path to a variable's use initializes it first, the use is OK.</li><li>Optional parameters must have a default value. If you don't pass an argument for an optional positional or named parameter, then the language fills it in with the default value. If you don't specify a default value, the default default value is <code>null</code>, and that doesn't fly if the parameter's type is non-nullable.So, if you want a parameter to be optional, you need to either make it nullable or specify a valid non-<code>null</code> default value.</li></ul>These restrictions sound onerous, but they aren't too bad in practice. They are very similar to the existing restrictions around <code>final</code> variables and you've likely been working with those for years without even really noticing. Also, remember that these only apply to non-nullable variables. You can always make the type nullable and then get the default initialization to <code>null</code>.Even so, the rules do cause friction. Fortunately, we have a suite of new language features to lubricate the most common patterns where these new limitations slow you down. First, though, it's time to talk about flow analysis.<div class="header-wrapper"><h2 id="flow-analysis">Flow analysis</h2><a class="heading-link" href="#flow-analysis" aria-label="Link to 'Flow analysis' section">#</a></div><a href="https://en.wikipedia.org/wiki/Control_flow_analysis">Control flow analysis</a> has been around in compilers for years. It's mostly hidden from users and used during compiler optimization, but some newer languages have started to use the same techniques for visible language features. Dart already has a dash of flow analysis in the form of type promotion:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// With (or without) null safety: bool isEmptyList(Object object) { if (object is List) { return object.isEmpty; // <-- OK! } else { return false; } }</code></pre></div></div>Note how on the marked line, we can call <code>isEmpty</code> on <code>object</code>. That method is defined on <code>List</code>, not <code>Object</code>. This works because the type checker looks at all of the <code>is</code> expressions and the control flow paths in the program. If the body of some control flow construct only executes when a certain <code>is</code> expression on a variable is true, then inside that body the variable's type is "promoted" to the tested type.In the example here, the then branch of the <code>if</code> statement only runs when <code>object</code> actually contains a list. Therefore, Dart promotes <code>object</code> to type <code>List</code> instead of its declared type <code>Object</code>. This is a handy feature, but it's pretty limited. Prior to null safety, the following functionally identical program did not work:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Without null safety: bool isEmptyList(Object object) { if (object is! List) return false; return object.isEmpty; // <-- Error! }</code></pre></div></div>Again, you can only reach the <code>.isEmpty</code> call when <code>object</code> contains a list, so this program is dynamically correct. But the type promotion rules were not smart enough to see that the <code>return</code> statement means the second statement can only be reached when <code>object</code> is a list.For null safety, we've taken this limited analysis and made it <a href="https://github.com/dart-lang/language/blob/main/resources/type-system/flow-analysis.md">much more powerful in several ways.</a><div class="header-wrapper"><h3 id="reachability-analysis">Reachability analysis</h3><a class="heading-link" href="#reachability-analysis" aria-label="Link to 'Reachability analysis' section">#</a></div>First off, we fixed the <a href="https://github.com/dart-lang/sdk/issues/18921">long-standing complaint</a> that type promotion isn't smart about early returns and other unreachable code paths. When analyzing a function, it now takes into account <code>return</code>, <code>break</code>, <code>throw</code>, and any other way execution might terminate early in a function. Under null safety, this function:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: bool isEmptyList(Object object) { if (object is! List) return false; return object.isEmpty; }</code></pre></div></div>Is now perfectly valid. Since the <code>if</code> statement will exit the function when <code>object</code> is not a <code>List</code>, Dart promotes <code>object</code> to be <code>List</code> on the second statement. This is a really nice improvement that helps a lot of Dart code, even stuff not related to nullability.<div class="header-wrapper"><h3 id="never-for-unreachable-code">Never for unreachable code</h3><a class="heading-link" href="#never-for-unreachable-code" aria-label="Link to 'Never for unreachable code' section">#</a></div>You can also program this reachability analysis. The new bottom type <code>Never</code> has no values. (What kind of value is simultaneously a <code>String</code>, <code>bool</code>, and <code>int</code>?) So what does it mean for an expression to have type <code>Never</code>? It means that expression can never successfully finish evaluating. It must throw an exception, abort, or otherwise ensure that the surrounding code expecting the result of the expression never runs.In fact, according to the language, the static type of a <code>throw</code> expression is <code>Never</code>. The type <code>Never</code> is declared in the core libraries and you can use it as a type annotation. Maybe you have a helper function to make it easier to throw a certain kind of exception:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: Never wrongType(String type, Object value) { throw ArgumentError('Expected $type, but was ${value.runtimeType}.'); }</code></pre></div></div>You might use it like so:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Point { final double x, y; bool operator ==(Object other) { if (other is! Point) wrongType('Point', other); return x == other.x && y == other.y; } // Constructor and hashCode... }</code></pre></div></div>This program analyzes without error. Notice that the last line of the <code>==</code> method accesses <code>.x</code> and <code>.y</code> on <code>other</code>. It has been promoted to <code>Point</code> even though the function doesn't have any <code>return</code> or <code>throw</code>. The control flow analysis knows that the declared type of <code>wrongType()</code> is <code>Never</code> which means the then branch of the <code>if</code> statement must abort somehow. Since the second statement can only be reached when <code>other</code> is a <code>Point</code>, Dart promotes it.In other words, using <code>Never</code> in your own APIs lets you extend Dart's reachability analysis.<div class="header-wrapper"><h3 id="definite-assignment-analysis">Definite assignment analysis</h3><a class="heading-link" href="#definite-assignment-analysis" aria-label="Link to 'Definite assignment analysis' section">#</a></div>I mentioned this one briefly with local variables. Dart needs to ensure a non-nullable local variable is always initialized before it is read. We use definite assignment analysis to be as flexible about that as possible. The language analyzes each function body and tracks the assignments to local variables and parameters through all control flow paths. As long as the variable is assigned on every path that reaches some use of a variable, the variable is considered initialized. This lets you declare a variable with no initializer and then initialize it afterwards using complex control flow, even when the variable has a non-nullable type.We also use definite assignment analysis to make final variables more flexible. Before null safety, it can be difficult to use <code>final</code> for local variables if you need to initialize them in any sort of interesting way:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: int tracingFibonacci(int n) { final int result; if (n < 2) { result = n; } else { result = tracingFibonacci(n - 2) + tracingFibonacci(n - 1); } print(result); return result; }</code></pre></div></div>This would be an error since the <code>result</code> variable is <code>final</code> but has no initializer. With the smarter flow analysis under null safety, this program is fine. The analysis can tell that <code>result</code> is definitely initialized exactly once on every control flow path, so the constraints for marking a variable <code>final</code> are satisfied.<div class="header-wrapper"><h3 id="type-promotion-on-null-checks">Type promotion on null checks</h3><a class="heading-link" href="#type-promotion-on-null-checks" aria-label="Link to 'Type promotion on null checks' section">#</a></div>The smarter flow analysis helps lots of Dart code, even code not related to nullability. But it's not a coincidence that we're making these changes now. We have partitioned types into nullable and non-nullable sets. If you have a value of a nullable type, you can't really do anything useful with it. In cases where the value is <code>null</code>, that restriction is good. It's preventing you from crashing.But if the value isn't <code>null</code>, it would be good to be able to move it over to the non-nullable side so you can call methods on it. Flow analysis is one of the primary ways to do this for local variables and parameters (and private final fields, as of Dart 3.2). We've extended type promotion to also look at <code>== null</code> and <code>!= null</code> expressions.If you check a local variable with nullable type to see if it is not <code>null</code>, Dart then promotes the variable to the underlying non-nullable type:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: String makeCommand(String executable, [List<String>? arguments]) { var result = executable; if (arguments != null) { result += ' ' + arguments.join(' '); } return result; }</code></pre></div></div>Here, <code>arguments</code> has a nullable type. Normally, that prohibits you from calling <code>.join()</code> on it. But because we have guarded that call in an <code>if</code> statement that checks to ensure the value is not <code>null</code>, Dart promotes it from <code>List<String>?</code> to <code>List<String></code> and lets you call methods on it or pass it to functions that expect non-nullable lists.This sounds like a fairly minor thing, but this flow-based promotion on null checks is what makes most existing Dart code work under null safety. Most Dart code is dynamically correct and does avoid throwing null reference errors by checking for <code>null</code> before calling methods. The new flow analysis on null checks turns that dynamic correctness into provable static correctness.It also, of course, works with the smarter analysis we do for reachability. The above function can be written just as well as:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: String makeCommand(String executable, [List<String>? arguments]) { var result = executable; if (arguments == null) return result; return result + ' ' + arguments.join(' '); }</code></pre></div></div>The language is also smarter about what kinds of expressions cause promotion. An explicit <code>== null</code> or <code>!= null</code> of course works. But explicit casts using <code>as</code>, or assignments, or the postfix <code>!</code> operator (which we'll cover <a href="#non-null-assertion-operator">later on</a>) also cause promotion. The general goal is that if the code is dynamically correct and it's reasonable to figure that out statically, the analysis should be clever enough to do so.Note that type promotion originally only worked on local variables, and now also works on private final fields as of Dart 3.2. For more information about working with non-local variables, see <a href="#working-with-nullable-fields">Working with nullable fields</a>.<div class="header-wrapper"><h3 id="unnecessary-code-warnings">Unnecessary code warnings</h3><a class="heading-link" href="#unnecessary-code-warnings" aria-label="Link to 'Unnecessary code warnings' section">#</a></div>Having smarter reachability analysis and knowing where <code>null</code> can flow through your program helps ensure that you add code to handle <code>null</code>. But we can also use that same analysis to detect code that you don't need. Before null safety, if you wrote something like:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: String checkList(List<Object> list) { if (list?.isEmpty ?? false) { return 'Got nothing'; } return 'Got something'; }</code></pre></div></div>Dart had no way of knowing if that null-aware <code>?.</code> operator is useful or not. For all it knows, you could pass <code>null</code> to the function. But in null-safe Dart, if you have annotated that function with the now non-nullable <code>List</code> type, then it knows <code>list</code> will never be <code>null</code>. That implies the <code>?.</code> will never do anything useful and you can and should just use <code>.</code>.To help you simplify your code, we've added warnings for unnecessary code like this now that the static analysis is precise enough to detect it. Using a null-aware operator or even a check like <code>== null</code> or <code>!= null</code> on a non-nullable type gets reported as a warning.And, of course, this plays with non-nullable type promotion too. Once a variable has been promoted to a non-nullable type, you get a warning if you redundantly check it again for <code>null</code>:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: String checkList(List<Object>? list) { if (list == null) return 'No list'; if (list?.isEmpty ?? false) { return 'Empty list'; } return 'Got something'; }</code></pre></div></div>You get a warning on the <code>?.</code> here because at the point that it executes, we already know <code>list</code> cannot be <code>null</code>. The goal with these warnings is not just to clean up pointless code. By removing unneeded checks for <code>null</code>, we ensure that the remaining meaningful checks stand out. We want you to be able to look at your code and see where <code>null</code> can flow.<div class="header-wrapper"><h2 id="working-with-nullable-types">Working with nullable types</h2><a class="heading-link" href="#working-with-nullable-types" aria-label="Link to 'Working with nullable types' section">#</a></div>We've now corralled <code>null</code> into the set of nullable types. With flow analysis, we can safely let some non-<code>null</code> values hop over the fence to the non-nullable side where we can use them. That's a big step, but if we stop here, the resulting system is still painfully restrictive. Flow analysis only helps with locals, parameters, and private final fields.To try to regain as much of the flexibility that Dart had before null safety鈥攁nd to go beyond it in some places鈥攚e have a handful of other new features.<div class="header-wrapper"><h3 id="smarter-null-aware-methods">Smarter null-aware methods</h3><a class="heading-link" href="#smarter-null-aware-methods" aria-label="Link to 'Smarter null-aware methods' section">#</a></div>Dart's null aware operator <code>?.</code> is much older than null safety. The runtime semantics state that if the receiver is <code>null</code> then the property access on the right-hand side is skipped and the expression evaluates to <code>null</code>:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Without null safety: String notAString = null; print(notAString?.length);</code></pre></div></div>Instead of throwing an exception, this prints "null". The null-aware operator is a nice tool for making nullable types usable in Dart. While we can't let you call methods on nullable types, we can and do let you use null-aware operators on them. The post-null safety version of the program is:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: String? notAString = null; print(notAString?.length);</code></pre></div></div>It works just like the previous one.However, if you've ever used null-aware operators in Dart, you've probably encountered an annoyance when using them in method chains. Let's say you want to see if the length of a potentially absent string is an even number (not a particularly realistic problem, I know, but work with me here):<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: String? notAString = null; print(notAString?.length.isEven);</code></pre></div></div>Even though this program uses <code>?.</code>, it still throws an exception at runtime. The problem is that the receiver of the <code>.isEven</code> expression is the result of the entire <code>notAString?.length</code> expression to its left. That expression evaluates to <code>null</code>, so we get a null reference error trying to call <code>.isEven</code>. If you've ever used <code>?.</code> in Dart, you probably learned the hard way that you have to apply the null-aware operator to every property or method in a chain after you use it once:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>String? notAString = null; print(notAString?.length?.isEven);</code></pre></div></div>This is annoying, but, worse, it obscures important information. Consider:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: showGizmo(Thing? thing) { print(thing?.doohickey?.gizmo); }</code></pre></div></div>Here's a question for you: Can the <code>doohickey</code> getter on <code>Thing</code> return <code>null</code>? It looks like it could because you're using <code>?.</code> on the result. But it may just be that the second <code>?.</code> is only there to handle cases where <code>thing</code> is <code>null</code>, not the result of <code>doohickey</code>. You can't tell.To address this, we borrowed a smart idea from C#'s design of the same feature. When you use a null-aware operator in a method chain, if the receiver evaluates to <code>null</code>, then the entire rest of the method chain is short-circuited and skipped. This means if <code>doohickey</code> has a non-nullable return type, then you can and should write:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: void showGizmo(Thing? thing) { print(thing?.doohickey.gizmo); }</code></pre></div></div>In fact, you'll get an unnecessary code warning on the second <code>?.</code> if you don't. If you see code like:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: void showGizmo(Thing? thing) { print(thing?.doohickey?.gizmo); }</code></pre></div></div>Then you know for certain it means that <code>doohickey</code> itself has a nullable return type. Each <code>?.</code> corresponds to a unique path that can cause <code>null</code> to flow into the method chain. This makes null-aware operators in method chains both more terse and more precise.While we were at it, we added a couple of other null-aware operators:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: // Null-aware cascade: receiver?..method(); // Null-aware index operator: receiver?[index];</code></pre></div></div>There isn't a null-aware function call operator, but you can write:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Allowed with or without null safety: function?.call(arg1, arg2);</code></pre></div></div><a id="null-assertion-operator"></a><div class="header-wrapper"><h3 id="non-null-assertion-operator">Non-null assertion operator</h3><a class="heading-link" href="#non-null-assertion-operator" aria-label="Link to 'Non-null assertion operator' section">#</a></div>The great thing about using flow analysis to move a nullable variable to the non-nullable side of the world is that doing so is provably safe. You get to call methods on the previously-nullable variable without giving up any of the safety or performance of non-nullable types.But many valid uses of nullable types can't be proven to be safe in a way that pleases static analysis. For example:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety, incorrectly: class HttpResponse { final int code; final String? error; HttpResponse.ok() : code = 200, error = null; HttpResponse.notFound() : code = 404, error = 'Not found'; @override String toString() { if (code == 200) return 'OK'; return 'ERROR $code ${error.toUpperCase()}'; } }</code></pre></div></div>If you try to run this, you get a compile error on the call to <code>toUpperCase()</code>. The <code>error</code> field is nullable because it won't have a value in a successful response. We can see by inspecting the class that we never access the <code>error</code> message when it is <code>null</code>. But that requires understanding the relationship between the value of <code>code</code> and the nullability of <code>error</code>. The type checker can't see that connection.In other words, we human maintainers of the code know that error won't be <code>null</code> at the point that we use it and we need a way to assert that. Normally, you assert types using an <code>as</code> cast, and you can do the same thing here:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: String toString() { if (code == 200) return 'OK'; return 'ERROR $code ${(error as String).toUpperCase()}'; }</code></pre></div></div>Casting <code>error</code> to the non-nullable <code>String</code> type will throw a runtime exception if the cast fails. Otherwise, it gives us a non-nullable string that we can then call methods on."Casting away nullability" comes up often enough that we have a new shorthand syntax. A postfix exclamation mark (<code>!</code>) takes the expression on the left and casts it to its underlying non-nullable type. So the above function is equivalent to:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: String toString() { if (code == 200) return 'OK'; return 'ERROR $code ${error!.toUpperCase()}'; }</code></pre></div></div>This one-character "bang operator" is particularly handy when the underlying type is verbose. It would be really annoying to have to write <code>as Map<TransactionProviderFactory, List<Set<ResponseFilter>>></code> just to cast away a single <code>?</code> from some type.Of course, like any cast, using <code>!</code> comes with a loss of static safety. The cast must be checked at runtime to preserve soundness and it may fail and throw an exception. But you have control over where these casts are inserted, and you can always see them by looking through your code.<div class="header-wrapper"><h3 id="late-variables">Late variables</h3><a class="heading-link" href="#late-variables" aria-label="Link to 'Late variables' section">#</a></div>The most common place where the type checker cannot prove the safety of code is around top-level variables and fields. Here is an example:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety, incorrectly: class Coffee { String _temperature; void heat() { _temperature = 'hot'; } void chill() { _temperature = 'iced'; } String serve() => _temperature + ' coffee'; } void main() { var coffee = Coffee(); coffee.heat(); coffee.serve(); }</code></pre></div></div>Here, the <code>heat()</code> method is called before <code>serve()</code>. That means <code>_temperature</code> will be initialized to a non-null value before it is used. But it's not feasible for a static analysis to determine that. (It might be possible for a trivial example like this one, but the general case of trying to track the state of each instance of a class is intractable.)Because the type checker can't analyze uses of fields and top-level variables, it has a conservative rule that non-nullable fields have to be initialized either at their declaration (or in the constructor initialization list for instance fields). So Dart reports a compile error on this class.You can fix the error by making the field nullable and then using null assertion operators on the uses:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Coffee { String? _temperature; void heat() { _temperature = 'hot'; } void chill() { _temperature = 'iced'; } String serve() => _temperature! + ' coffee'; }</code></pre></div></div>This works fine. But it sends a confusing signal to the maintainer of the class. By marking <code>_temperature</code> nullable, you imply that <code>null</code> is a useful, meaningful value for that field. But that's not the intent. The <code>_temperature</code> field should never be observed in its <code>null</code> state.To handle the common pattern of state with delayed initialization, we've added a new modifier, <code>late</code>. You can use it like this:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Coffee { late String _temperature; void heat() { _temperature = 'hot'; } void chill() { _temperature = 'iced'; } String serve() => _temperature + ' coffee'; }</code></pre></div></div>Note that the <code>_temperature</code> field has a non-nullable type, but is not initialized. Also, there's no explicit null assertion when it's used. There are a few models you can apply to the semantics of <code>late</code>, but I think of it like this: The <code>late</code> modifier means "enforce this variable's constraints at runtime instead of at compile time". It's almost like the word "late" describes when it enforces the variable's guarantees.In this case, since the field is not definitely initialized, every time the field is read, a runtime check is inserted to make sure it has been assigned a value. If it hasn't, an exception is thrown. Giving the variable the type <code>String</code> means "you should never see me with a value other than a string" and the <code>late</code> modifier means "verify that at runtime".In some ways, the <code>late</code> modifier is more "magical" than using <code>?</code> because any use of the field could fail, and there isn't anything textually visible at the use site. But you do have to write <code>late</code> at the declaration to get this behavior, and our belief is that seeing the modifier there is explicit enough for this to be maintainable.In return, you get better static safety than using a nullable type. Because the field's type is non-nullable now, it is a compile error to try to assign <code>null</code> or a nullable <code>String</code> to the field. The <code>late</code> modifier lets you defer initialization, but still prohibits you from treating it like a nullable variable.<div class="header-wrapper"><h3 id="lazy-initialization">Lazy initialization</h3><a class="heading-link" href="#lazy-initialization" aria-label="Link to 'Lazy initialization' section">#</a></div>The <code>late</code> modifier has some other special powers too. It may seem paradoxical, but you can use <code>late</code> on a field that has an initializer:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Weather { late int _temperature = _readThermometer(); }</code></pre></div></div>When you do this, the initializer becomes lazy. Instead of running it as soon as the instance is constructed, it is deferred and run lazily the first time the field is accessed. In other words, it works exactly like an initializer on a top-level variable or static field. This can be handy when the initialization expression is costly and may not be needed.Running the initializer lazily gives you an extra bonus when you use <code>late</code> on an instance field. Usually instance field initializers cannot access <code>this</code> because you don't have access to the new object until all field initializers have completed. But with a <code>late</code> field, that's no longer true, so you can access <code>this</code>, call methods, or access fields on the instance.<div class="header-wrapper"><h3 id="late-final-variables">Late final variables</h3><a class="heading-link" href="#late-final-variables" aria-label="Link to 'Late final variables' section">#</a></div>You can also combine <code>late</code> with <code>final</code>:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Coffee { late final String _temperature; void heat() { _temperature = 'hot'; } void chill() { _temperature = 'iced'; } String serve() => _temperature + ' coffee'; }</code></pre></div></div>Unlike normal <code>final</code> fields, you do not have to initialize the field in its declaration or in the constructor initialization list. You can assign to it later at runtime. But you can only assign to it once, and that fact is checked at runtime. If you try to assign to it more than once鈥攍ike calling both <code>heat()</code> and <code>chill()</code> here鈥攖he second assignment throws an exception. This is a great way to model state that gets initialized eventually and is immutable afterwards.In other words, the new <code>late</code> modifier in combination with Dart's other variable modifiers covers most of the feature space of <code>lateinit</code> in Kotlin and <code>lazy</code> in Swift. You can even use it on local variables if you want a little local lazy evaluation.<div class="header-wrapper"><h3 id="required-named-parameters">Required named parameters</h3><a class="heading-link" href="#required-named-parameters" aria-label="Link to 'Required named parameters' section">#</a></div>To guarantee that you never see a <code>null</code> parameter with a non-nullable type, the type checker requires all optional parameters to either have a nullable type or a default value. What if you want to have a named parameter with a non-nullable type and no default value? That would imply that you want to require the caller to always pass it. In other words, you want a parameter that is named but not optional.I visualize the various kinds of Dart parameters with this table:<div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code> mandatory optional +------------+------------+ positional | f(int x) | f([int x]) | +------------+------------+ named | ??? | f({int x}) | +------------+------------+</code></pre></div></div>For unclear reasons, Dart has long supported three corners of this table but left the combination of named+mandatory empty. With null safety, we filled that in. You declare a required named parameter by placing <code>required</code> before the parameter:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: function({int? a, required int? b, int? c, required int? d}) {}</code></pre></div></div>Here, all the parameters must be passed by name. The parameters <code>a</code> and <code>c</code> are optional and can be omitted. The parameters <code>b</code> and <code>d</code> are required and must be passed. Note that required-ness is independent of nullability. You can have required named parameters of nullable types, and optional named parameters of non-nullable types (if they have a default value).This is another one of those features that I think makes Dart better regardless of null safety. It simply makes the language feel more complete to me.<div class="header-wrapper"><h3 id="abstract-fields">Abstract fields</h3><a class="heading-link" href="#abstract-fields" aria-label="Link to 'Abstract fields' section">#</a></div>One of the neat features of Dart is that it upholds a thing called the <a href="https://en.wikipedia.org/wiki/Uniform_access_principle">uniform access principle</a>. In human terms it means that fields are indistinguishable from getters and setters. It's an implementation detail whether a "property" in some Dart class is computed or stored. Because of this, when defining an interface using an abstract class, it's typical to use a field declaration:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>abstract class Cup { Beverage contents; }</code></pre></div></div>The intent is that users only implement that class and don't extend it. The field syntax is simply a shorter way of writing a getter/setter pair:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>abstract class Cup { Beverage get contents; set contents(Beverage); }</code></pre></div></div>But Dart doesn't know that this class will never be used as a concrete type. It sees that <code>contents</code> declaration as a real field. And, unfortunately, that field is non-nullable and has no initializer, so you get a compile error.One fix is to use explicit abstract getter/setter declarations like in the second example. But that's a little verbose, so with null safety we also added support for explicit abstract field declarations:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>abstract class Cup { abstract Beverage contents; }</code></pre></div></div>This behaves exactly like the second example. It simply declares an abstract getter and setter with the given name and type.<div class="header-wrapper"><h3 id="working-with-nullable-fields">Working with nullable fields</h3><a class="heading-link" href="#working-with-nullable-fields" aria-label="Link to 'Working with nullable fields' section">#</a></div>These new features cover many common patterns and make working with <code>null</code> pretty painless most of the time. But even so, our experience is that nullable fields can still be difficult. In cases where you can make the field <code>late</code> and non-nullable, you're golden. But in many cases you need to check to see if the field has a value, and that requires making it nullable so you can observe the <code>null</code>.Nullable fields that are both private and final are able to type promote (barring <a href="/tools/non-promotion-reasons">some particular reasons</a>). If you can't make a field private and final for whatever reason, you'll still need a workaround.For example, you might expect this to work:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety, incorrectly: class Coffee { String? _temperature; void heat() { _temperature = 'hot'; } void chill() { _temperature = 'iced'; } void checkTemp() { if (_temperature != null) { print('Ready to serve ' + _temperature + '!'); } } String serve() => _temperature! + ' coffee'; }</code></pre></div></div>Inside <code>checkTemp()</code>, we check to see if <code>_temperature</code> is <code>null</code>. If not, we access it and end up calling <code>+</code> on it. Unfortunately, this is not allowed.Flow-based type promotion can only apply to fields that are both private and final. Otherwise, static analysis cannot prove that the field's value doesn't change between the point that you check for <code>null</code> and the point that you use it. (Consider that in pathological cases, the field itself could be overridden by a getter in a subclass that returns <code>null</code> the second time it is called.)So, since we care about soundness, public and/or non-final fields don't promote, and the above method does not compile. This is annoying. In simple cases like here, your best bet is to slap a <code>!</code> on the use of the field. It seems redundant, but that's more or less how Dart behaves today.Another pattern that helps is to copy the field to a local variable first and then use that instead:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: void checkTemp() { var temperature = _temperature; if (temperature != null) { print('Ready to serve ' + temperature + '!'); } }</code></pre></div></div>Since the type promotion does apply to locals, this now works fine. If you need to change the value, just remember to store back to the field and not just the local.For more information on handling these and other type promotion issues, see <a href="/tools/non-promotion-reasons">Fixing type promotion failures</a>.<div class="header-wrapper"><h3 id="nullability-and-generics">Nullability and generics</h3><a class="heading-link" href="#nullability-and-generics" aria-label="Link to 'Nullability and generics' section">#</a></div>Like most modern statically-typed languages, Dart has generic classes and generic methods. They interact with nullability in a few ways that seem counter-intuitive but make sense once you think through the implications. First is that "is this type nullable?" is no longer a simple yes or no question. Consider:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Box<T> { final T object; Box(this.object); } void main() { Box<String>('a string'); Box<int?>(null); }</code></pre></div></div>In the definition of <code>Box</code>, is <code>T</code> a nullable type or a non-nullable type? As you can see, it can be instantiated with either kind. The answer is that <code>T</code> is a potentially nullable type. Inside the body of a generic class or method, a potentially nullable type has all of the restrictions of both nullable types and non-nullable types.The former means you can't call any methods on it except the handful defined on Object. The latter means that you must initialize any fields or variables of that type before they're used. This can make type parameters pretty hard to work with.In practice, a few patterns show up. In collection-like classes where the type parameter can be instantiated with any type at all, you just have to deal with the restrictions. In most cases, like the example here, it means ensuring you do have access to a value of the type argument's type whenever you need to work with one. Fortunately, collection-like classes rarely call methods on their elements.In places where you don't have access to a value, you can make the use of the type parameter nullable:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Box<T> { T? object; Box.empty(); Box.full(this.object); }</code></pre></div></div>Note the <code>?</code> on the declaration of <code>object</code>. Now the field has an explicitly nullable type, so it is fine to leave it uninitialized.When you make a type parameter type nullable like <code>T?</code> here, you may need to cast the nullability away. The correct way to do that is using an explicit <code>as T</code> cast, not the <code>!</code> operator:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Box<T> { T? object; Box.empty(); Box.full(this.object); T unbox() => object as T; }</code></pre></div></div>The <code>!</code> operator always throws if the value is <code>null</code>. But if the type parameter has been instantiated with a nullable type, then <code>null</code> is a perfectly valid value for <code>T</code>:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: void main() { var box = Box<int?>.full(null); print(box.unbox()); }</code></pre></div></div>This program should run without error. Using <code>as T</code> accomplishes that. Using <code>!</code> would throw an exception.Other generic types have some bound that restricts the kinds of type arguments that can be applied:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Interval<T extends num> { T min, max; Interval(this.min, this.max); bool get isEmpty => max <= min; }</code></pre></div></div>If the bound is non-nullable, then the type parameter is also non-nullable. This means you have the restrictions of non-nullable types鈥攜ou can't leave fields and variables uninitialized. The example class here must have a constructor that initializes the fields.In return for that restriction, you can call any methods on values of the type parameter type that are declared on its bound. Having a non-nullable bound does, however, prevent users of your generic class from instantiating it with a nullable type argument. That's probably a reasonable limitation for most classes.You can also use a nullable bound:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: class Interval<T extends num?> { T min, max; Interval(this.min, this.max); bool get isEmpty { var localMin = min; var localMax = max; // No min or max means an open-ended interval. if (localMin == null || localMax == null) return false; return localMax <= localMin; } }</code></pre></div></div>This means that in the body of the class you get the flexibility of treating the type parameter as nullable, but you also have the limitations of nullability. You can't call anything on a variable of that type unless you deal with the nullability first. In the example here, we copy the fields in local variables and check those locals for <code>null</code> so that flow analysis promotes them to non-nullable types before we use <code><=</code>.Note that a nullable bound does not prevent users from instantiating the class with non-nullable types. A nullable bound means that the type argument can be nullable, not that it must. (In fact, the default bound on type parameters if you don't write an <code>extends</code> clause is the nullable bound <code>Object?</code>.) There is no way to require a nullable type argument. If you want uses of the type parameter to reliably be nullable and be implicitly initialized to <code>null</code>, you can use <code>T?</code> inside the body of the class.<div class="header-wrapper"><h2 id="core-library-changes">Core library changes</h2><a class="heading-link" href="#core-library-changes" aria-label="Link to 'Core library changes' section">#</a></div>There are a couple of other tweaks here and there in the language, but they are minor. Things like the default type of a <code>catch</code> with no <code>on</code> clause is now <code>Object</code> instead of <code>dynamic</code>. Fallthrough analysis in switch statements uses the new flow analysis.The remaining changes that really matter to you are in the core libraries. Before we embarked on the Grand Null Safety Adventure, we worried that it would turn out there was no way to make our core libraries null safe without massively breaking the world. It turned out not so dire. There are a few significant changes, but for the most part, the migration went smoothly. Most core libraries either did not accept <code>null</code> and naturally move to non-nullable types, or do and gracefully accept it with a nullable type.There are a few important corners, though:<div class="header-wrapper"><h3 id="the-map-index-operator-is-nullable">The Map index operator is nullable</h3><a class="heading-link" href="#the-map-index-operator-is-nullable" aria-label="Link to 'The Map index operator is nullable' section">#</a></div>This isn't really a change, but more a thing to know. The index <code>[]</code> operator on the Map class returns <code>null</code> if the key isn't present. This implies that the return type of that operator must be nullable: <code>V?</code> instead of <code>V</code>.We could have changed that method to throw an exception when the key isn't present and then given it an easier-to-use non-nullable return type. But code that uses the index operator and checks for <code>null</code> to see if the key is absent is very common, around half of all uses based on our analysis. Breaking all of that code would have set the Dart ecosystem aflame.Instead, the runtime behavior is the same and thus the return type is obliged to be nullable. This means you generally cannot immediately use the result of a map lookup:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety, incorrectly: var map = {'key': 'value'}; print(map['key'].length); // Error.</code></pre></div></div>This gives you a compile error on the attempt to call <code>.length</code> on a nullable string. In cases where you know the key is present you can teach the type checker by using <code>!</code>:<div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>// Using null safety: var map = {'key': 'value'}; print(map['key']!.length); // OK.</code></pre></div></div>We considered adding another method to Map that would do this for you: look up the key, throw if not found, or return a non-nullable value otherwise. But what to call it? No name would be shorter than the single-character <code>!</code>, and no method name would be clearer than seeing a <code>!</code> with its built-in semantics right there at the call site. So the idiomatic way to access a known-present element in a map is to use <code>[]!</code>. You get used to it.<div class="header-wrapper"><h3 id="no-unnamed-list-constructor">No unnamed List constructor</h3><a class="heading-link" href="#no-unnamed-list-constructor" aria-label="Link to 'No unnamed List constructor' section">#</a></div>The unnamed constructor on <code>List</code> creates a new list with the given size but does not initialize any of the elements. This would poke a very large hole in the soundness guarantees if you created a list of a non-nullable type and then accessed an element.To avoid that, we have removed the constructor entirely. It is an error to call <code>List()</code> in null-safe code, even with a nullable type. That sounds scary, but in practice most code creates lists using list literals, <code>List.filled()</code>, <code>List.generate()</code>, or as a result of transforming some other collection. For the edge case where you want to create an empty list of some type, we added a new <code>List.empty()</code> constructor.The pattern of creating a completely uninitialized list has always felt out of place in Dart, and now it is even more so. If you have code broken by this, you can always fix it by using one of the many other ways to produce a list.<div class="header-wrapper"><h3 id="cannot-set-a-larger-length-on-non-nullable-lists">Cannot set a larger length on non-nullable lists</h3><a class="heading-link" href="#cannot-set-a-larger-length-on-non-nullable-lists" aria-label="Link to 'Cannot set a larger length on non-nullable lists' section">#</a></div>This is little known, but the <code>length</code> getter on <code>List</code> also has a corresponding setter. You can set the length to a shorter value to truncate the list. And you can also set it to a longer length to pad the list with uninitialized elements.If you were to do that with a list of a non-nullable type, you'd violate soundness when you later accessed those unwritten elements. To prevent that, the <code>length</code> setter will throw a runtime exception if (and only if) the list has a non-nullable element type and you set it to a longer length. It is still fine to truncate lists of all types, and you can grow lists of nullable types.There is an important consequence of this if you define your own list types that extend <code>ListBase</code> or apply <code>ListMixin</code>. Both of those types provide an implementation of <code>insert()</code> that previously made room for the inserted element by setting the length. That would fail with null safety, so instead we changed the implementation of <code>insert()</code> in <code>ListMixin</code> (which <code>ListBase</code> shares) to call <code>add()</code> instead. Your custom list class should provide a definition of <code>add()</code> if you want to be able to use that inherited <code>insert()</code> method.<div class="header-wrapper"><h3 id="cannot-access-iterator-current-before-or-after-iteration">Cannot access Iterator.current before or after iteration</h3><a class="heading-link" href="#cannot-access-iterator-current-before-or-after-iteration" aria-label="Link to 'Cannot access Iterator.current before or after iteration' section">#</a></div>The <code>Iterator</code> class is the mutable "cursor" class used to traverse the elements of a type that implements <code>Iterable</code>. You are expected to call <code>moveNext()</code> before accessing any elements to advance to the first element. When that method returns <code>false</code>, you have reached the end and there are no more elements.It used to be that <code>current</code> returned <code>null</code> if you called it either before calling <code>moveNext()</code> the first time or after iteration finished. With null safety, that would require the return type of <code>current</code> to be <code>E?</code> and not <code>E</code>. That in turn means every element access would require a runtime <code>null</code> check.Those checks would be useless given that almost no one ever accesses the current element in that erroneous way. Instead, we have made the type of <code>current</code> be <code>E</code>. Since there may be a value of that type available before or after iterating, we've left the iterator's behavior undefined if you call it when you aren't supposed to. Most implementations of <code>Iterator</code> throw a <code>StateError</code>.<div class="header-wrapper"><h2 id="summary">Summary</h2><a class="heading-link" href="#summary" aria-label="Link to 'Summary' section">#</a></div>That is a very detailed tour through all of the language and library changes around null safety. It's a lot of stuff, but this is a pretty big language change. More importantly, we wanted to get to a point where Dart still feels cohesive and usable. That requires changing not just the type system, but a number of other usability features around it. We didn't want it to feel like null safety was bolted on.The core points to take away are:<ul><li>Types are non-nullable by default and made nullable by adding <code>?</code>.</li><li>Optional parameters must be nullable or have a default value. You can use <code>required</code> to make named parameters non-optional. Non-nullable top-level variables and static fields must have initializers. Non-nullable instance fields must be initialized before the constructor body begins.</li><li>Method chains after null-aware operators short circuit if the receiver is <code>null</code>. There are new null-aware cascade (<code>?..</code>) and index (<code>?[]</code>) operators. The postfix null assertion "bang" operator (<code>!</code>) casts its nullable operand to the underlying non-nullable type.</li><li>Flow analysis lets you safely turn nullable local variables and parameters (and private final fields, as of Dart 3.2) into usable non-nullable ones. The new flow analysis also has smarter rules for type promotion, missing returns, unreachable code, and variable initialization.</li><li>The <code>late</code> modifier lets you use non-nullable types and <code>final</code> in places you otherwise might not be able to, at the expense of runtime checking. It also gives you lazy-initialized fields.</li><li>The <code>List</code> class is changed to prevent uninitialized elements.</li></ul>Finally, once you absorb all of that and get your code into the world of null safety, you get a sound program that the compilers can optimize and where every place a runtime error can occur is visible in your code. We hope you feel that's worth the effort to get there.Unless stated otherwise, the documentation on this site reflects Dart 3.5.4. Page last updated on 2024-05-14. <a href="https://github.com/dart-lang/site-www/tree/main/src/content/null-safety/understanding-null-safety.md" target="_blank" rel="noopener">View source</a> or <a href="https://github.com/dart-lang/site-www/issues/new?template=1_page_issue.yml&page-url=https://dart.dev/null-safety/understanding-null-safety/&page-source=https://github.com/dart-lang/site-www/tree/main/src/content/null-safety/understanding-null-safety.md" title="Report an issue with this page" target="_blank" rel="noopener">report an issue</a>.</div></article></main><footer id="page-footer"><div class="footer-section footer-main"><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart" width="164"></a><div class="footer-social-links"><a href="https://medium.com/dartlang" target="_blank" rel="noopener" title="Medium blog"><svg><use href="/assets/img/social/medium.svg#medium"></use></svg> </a><a href="https://github.com/dart-lang" target="_blank" rel="noopener" title="GitHub"><svg><use href="/assets/img/social/github.svg#github"></use></svg> </a><a href="https://twitter.com/dart_lang" target="_blank" rel="noopener" title="X (Twitter)"><svg><use href="/assets/img/social/x.svg#x"></use></svg></a></div></div><div class="footer-section footer-tray"><div class="footer-licenses">Except as otherwise noted, this site is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>, and code samples are licensed under the <a href="https://opensource.org/licenses/BSD-3-Clause">3-Clause BSD License</a>.</div><div class="footer-utility-links"><ul><li><a href="/terms" title="Terms of use">Terms</a></li><li><a href="https://policies.google.com/privacy" target="_blank" rel="noopener" title="Privacy policy">Privacy</a></li><li><a href="/security" title="Security philosophy and practices">Security</a></li></ul></div></div></footer></body></html>