Improve Container color/decoration error message clarity (#178823)

777genius · dkwingsmt · web-flow · commit a634f089ab93 · 2025-12-31T00:08:37.000Z
## Description This PR improves the clarity of the error message shown when developers provide both `color` and `decoration` parameters to a `Container` widget. ### Problem The previous assertion message was confusing and contradictory: ``` Cannot provide both a color and a decoration To provide both, use "decoration: BoxDecoration(color: color)". ``` This message stated "Cannot provide **both**" but then suggested "To provide **both**, use...", which confused developers about the actual requirement. The suggestion appeared to offer a workaround to use both parameters together, when in fact it was explaining how to migrate from using `color` to using `decoration` exclusively. ### Solution Updated the assertion message to clearly explain: - The `color` parameter is a shorthand for `decoration: BoxDecoration(color: color)` - Developers should use **either** `color` OR `decoration`, not both - To use both a color and other decoration properties (like borders, shadows, etc.), set the color within the `BoxDecoration` instead **New message:** ``` Cannot provide both a color and a decoration. The color argument is just a shorthand for "decoration: BoxDecoration(color: color)". To use both a color and other decoration properties, set the color in the BoxDecoration instead. ``` ## Related Issues Fixes #119484 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing.  [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md Co-authored-by: Tong Mu <dkwingsmt@users.noreply.github.com>
diff --git a/packages/flutter/lib/src/widgets/container.dart b/packages/flutter/lib/src/widgets/container.dart
@@ -275,8 +275,9 @@ class Container extends StatelessWidget {
        assert(decoration != null || clipBehavior == Clip.none),
        assert(
          color == null || decoration == null,
-         'Cannot provide both a color and a decoration\n'
-         'To provide both, use "decoration: BoxDecoration(color: color)".',
+         'Cannot provide both a color and a decoration.\n'
+         'The color argument is just a shorthand for "decoration: BoxDecoration(color: color)".\n'
+         'To use both a color and other decoration properties, set the color in the BoxDecoration instead.',
        ),
        constraints = (width != null || height != null)
            ? constraints?.tighten(width: width, height: height) ??
