Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

flutter_local_notifications throws ArgumentError: iOS settings must be set

ErrorArgumentError (Invalid argument(s): iOS settings must be set when targeting iOS platform.)

Short answer

The plugin's initialize call checks that InitializationSettings holds settings for the platform the app is running on. If the iOS field is null on an iPhone, it throws this ArgumentError. Pass DarwinInitializationSettings as iOS, and as macOS if you run there; the Android and Linux fields follow the same rule.

  • Applies to Flutter 3.x, flutter_local_notifications current release, iOS 18+
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find where the plugin is initialised and read which fields of InitializationSettings are filled in.

    grep -rn "InitializationSettings(" lib/
  2. 2Match what you see, then jump to its fix

    1. 1The message names iOS and appears only when the app runs on an iPhone or iPad simulator; Android works.The iOS field of InitializationSettings is missingFix
    2. 2The message says macOS settings or Android settings instead of iOS.The same app also runs on macOS (or Android) and that field is emptyFix
    3. 3Your code still builds the settings with the old IOSInitializationSettings class, or calls initialize with a positional argument.initialize() is called with a settings object built for the old APIFix

What does the error look like?

  • ArgumentError (Invalid argument(s): iOS settings must be set when targeting iOS platform.)
  • Android settings must be set when targeting Android platform.
  • macOS settings must be set when targeting macOS platform.

Cause 1 of 3

The iOS field of InitializationSettings is missing

1Check

Look at the InitializationSettings constructor call. If it only passes android:, the iOS value is null.

grep -rn -A4 "InitializationSettings(" lib/

2Fix

Create DarwinInitializationSettings and pass it as iOS. The plugin's README shows this form, and all fields are nullable so you must fill each platform you run on.

const android = AndroidInitializationSettings('app_icon');
const darwin = DarwinInitializationSettings();
const settings = InitializationSettings(android: android, iOS: darwin);
await flutterLocalNotificationsPlugin.initialize(settings: settings);

3Verify

Run on an iOS simulator and confirm initialize() completes.

flutter run -d ios

Confirmed by pub.dev

Did this fix it?

Cause 2 of 3

The same app also runs on macOS (or Android) and that field is empty

1Check

Each target platform needs its own field. The same Darwin settings object can be passed to both iOS and macOS.

flutter devices

2Fix

Set every platform you ship to. The README passes one DarwinInitializationSettings object to both iOS and macOS.

final settings = InitializationSettings(
  android: AndroidInitializationSettings('app_icon'),
  iOS: darwin,
  macOS: darwin,
);

3Verify

Run on each platform you ship and confirm there is no ArgumentError.

flutter run -d macos

Confirmed by pub.dev

Did this fix it?

Cause 3 of 3

initialize() is called with a settings object built for the old API

1Check

Look for IOSInitializationSettings in your code. The README says IOSInitializationSettings extends DarwinInitializationSettings and the current call passes settings by name.

grep -rn "IOSInitializationSettings" lib/

2Fix

Switch to DarwinInitializationSettings and the named settings: argument shown in the current README.

await flutterLocalNotificationsPlugin.initialize(
  settings: initializationSettings,
  onDidReceiveNotificationResponse: onDidReceiveNotificationResponse,
);

3Verify

Run flutter analyze and then launch the app.

flutter analyze

Confirmed by pub.dev

Did this fix it?

How do I stop it coming back?

  • Build one InitializationSettings object that lists every platform you ship to.
  • Read the package changelog before upgrading flutter_local_notifications; initialisation signatures changed between major versions.
  • Run the app once on every target platform after changing initialisation code.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.