Q: What do I get a "FlexColorScheme WARNING: primaryLightRef is null, but primary is defined"?

[maxfrees]

I/flutter (25901): FlexColorScheme WARNING: primaryLightRef is null, but primary is defined, primaryLightRef may be needed. Set primaryLightRef to the same color as primary in your LIGHT theme mode setup to get correct values for "fixed" colors for your dark ColorScheme or to seed with same color as your light theme primary. If primary is already set to same color as light mode primary and it is only used as seed in dark mode, defining primaryLightRef is not necessary.

[rydmike]

Hi @maxfrees, thanks for your question.

Yes, this is an expected informational debug print, it is only shown/printed in debug mode build and only when there might be a point in doing so. It is intended to make you aware of potentially incomplete configuration to make a matching dark mode ColorScheme that follows the Material-3 design intent.

This is what triggers it:

    // In debug mode warn to console about missing LightRef colors when they
    // are used in a combo that may require them.
    if (kDebugMode) {
      if (primary != null &&
          primaryLightRef == null &&
          ((!seed.useKeyColors &&
                  (fixedColorStyle ?? FlexFixedColorStyle.computed) ==
                      FlexFixedColorStyle.computed) ||
              seed.useKeyColors)) {
        debugPrint('FlexColorScheme WARNING: primaryLightRef is null, but '
            'primary is defined, primaryLightRef may be needed. '
            'Set primaryLightRef to the same color '
            'as primary in your LIGHT theme mode setup to get correct values '
            'for "fixed" colors for your dark ColorScheme or to seed with '
            'same color as your light theme primary. If primary is already '
            'set to same color as light mode primary and it is only used as '
            'seed in dark mode, defining primaryLightRef is not necessary.');
      }
      if (secondary != null &&
          secondaryLightRef == null &&
          ((!seed.useKeyColors &&
                  (fixedColorStyle ?? FlexFixedColorStyle.computed) ==
                      FlexFixedColorStyle.computed) ||
              seed.useKeyColors)) {
        debugPrint('FlexColorScheme WARNING: secondaryLightRef is null, but '
            'secondary is defined, secondaryLightRef may be needed. '
            'Set secondaryLightRef to the same color '
            'as secondary in your LIGHT theme mode setup to get correct values '
            'for "fixed" colors for your dark ColorScheme or to seed with '
            'same color as your light theme secondary. If secondary is already '
            'set to same color as light mode secondary and it is only used as '
            'seed in dark mode, defining secondaryLightRef is not necessary.');
      }
      if (tertiary != null &&
          tertiaryLightRef == null &&
          ((!seed.useKeyColors &&
                  (fixedColorStyle ?? FlexFixedColorStyle.computed) ==
                      FlexFixedColorStyle.computed) ||
              seed.useKeyColors)) {
        debugPrint('FlexColorScheme WARNING: tertiaryLightRef is null, but '
            'tertiary is defined, tertiaryLightRef may be needed. '
            'Set tertiaryLightRef to the same color '
            'as tertiary in your LIGHT theme mode setup to get correct values '
            'for "fixed" colors for your dark ColorScheme or to seed with '
            'same color as your light theme tertiary. If tertiary is already '
            'set to same color as light mode tertiary and it is only used as '
            'seed in dark mode, defining tertiaryLightRef is not necessary.');
      }
    }

If you have made your theme with Themes Playground V8 you should typically not get into a situation where you see this information.

But if you make a totally custom theme using FlexColorScheme or just upgrade a Playground Theme from v7 to v8 that uses custom colors, then you may run into this warning.

In order for FlexColorScheme to be able to to compute or seed generate the colors for all the ColorScheme Fixed and FixedDim colors and their on colors in dark mode, so that they get the same color values as in light mode, which they according to M3 spec should have, a dark mode FlexColorScheme needs to know what colors where used as seed keys or input colors for computed/seeded version of these colors in the corresponding light theme.

The primaryLightRef, secondaryLightRef and tertiaryLightRef is the mechanism for providing this information to the mode dark theme. They should contain the color values for the used primary, secondary and tertiary colors in light mode. To be used either for seed generation of the fixed colors, of for their FCS computed version, depends on which version of fixed colors you have used.

When using built-in schemes, this is handled automatically, and when using Playground and making custom colored schemes with it, it also takes care of this for you.

Color math and logics for M3 ColorScheme are bit complex, and got more confusing in Flutter 3.22 when so many new colors where added with specific roles.

If you are not using any of the fixed Colors in your app, meaning these:

Then you can safely ignore the informational warning.

By default Flutter's built-in components do not yet use these colors for anything either. They are just there to give you more options for your design by giving you a set of ColorScheme colors, that have the same color values in both light and dark theme mode.

See https://m3.material.io/styles/color/roles#26b6a882-064d-4668-b096-c51142477850

---

Your question and report was a bit short, so it was difficult to figure out what you wanted to know about it, or if you were just concerned that it was a bug.

In any case I hope this explains it and answers your questions.

I will convert this to a Question and Answer, as it it is likely a topic others will wonder about at some point too.

[maxfrees]

Thanks for the answer, each time your answer is very rewarding for us, and I'll try next week to see if I can add primaryLightRef to solve this prompt