Skip to content

Latest commit

 

History

History
271 lines (192 loc) · 9.86 KB

troubleshooting.md

File metadata and controls

271 lines (192 loc) · 9.86 KB

When it does not work

Almost every failure in this space is silent. The build succeeds, the code is generated, the app runs — and Siri has never heard of your action. That is not a bug in your project; it is what App Intents and AppFunctions do when something is not where the system expects it, and it is why doctor exists.

Start here, on either platform:

dart run os_intents_cli:os_intents build   # everything, in order

Then read the artefact rather than the source:

flutter build ios --simulator --debug
dart run os_intents_cli:os_intents doctor

doctor reads the file the OS itself indexes. If your intent is not in its output, no amount of restarting the phone will help, and the rest of this page is about why it might not be.


iOS

Nothing appears in Shortcuts, Spotlight or Siri

The generated Swift is not in the Runner target. It compiles into nothing, and nothing reports it:

dart run os_intents_cli:os_intents install --check

If that lists files, run install without --check. doctor on a bundle built afterwards should then list them.

You did not rebuild. App Intents metadata is extracted by Xcode at compile time, into Metadata.appintents inside the bundle. Nothing declared at runtime from Dart is ever visible to the system, and a hot reload changes nothing. After any change to an annotation: rebuild, and reinstall the app.

iOS has not re-indexed yet. Deleting the app and installing it again is the blunt fix. On a simulator, xcrun simctl reinstalls are usually enough.

The action appears, but a spoken phrase does nothing

Another AppShortcutsProvider won. iOS selects exactly one per app and drops the rest without an error or a warning. sync refuses to write ours when it finds one you wrote yourself, and doctor names the provider the system actually selected:

Spoken phrases (3 via Runner.OsIntentsShortcuts)

If that says something other than OsIntentsShortcuts, your phrases are in the losing provider. Move them into @AppIntent(phrases: …) or delete the other provider.

root.ssu.yaml is missing. doctor reports it on the last line of the phrases section. Without it Siri has no phrase model, and only the tap paths work.

The phrase does not name the app. Every phrase has to contain $app, which expands to \(.applicationName). The generator refuses a phrase without it, so this fails at build time rather than at App Review.

OsIntents.donate returns false

On Android that is the documented answer: there is nothing to donate to.

On iOS it means one of the links broke, and the check that separates them is doctor — a donation needs the same generated code an invocation does. Most often the app was built before OsIntentsDonations.swift existed, or that file is not in the Runner target:

dart run os_intents_cli:os_intents build

An id nothing declares also returns false, deliberately: a typo in a donation should not throw in a code path that only exists to help the user later.

iOS never suggests the action, even though donations succeed

Donation is a hint to a ranking model, not an instruction. iOS decides what to surface from days of real use, so a handful of donations on a simulator will not produce a suggestion, and nothing in this package can make one appear. donate returning true means the system accepted the intent — that is the whole of what is observable.

The app opens when it was supposed to stay closed

Execution.foreground opens the app by design. Execution.background does not — but only on iOS, and only through App Intents. On Android's app-shortcuts layer every shortcut starts an Activity; see below.

The handler never runs, or the intent times out

OsIntents.install() has not been called yet. It must run before runApp:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await OsIntents.install($osIntentsRegistry);
  runApp(const MyApp());
}

An intent can be what launched the app, and the native side buffers that invocation only until this future resolves. Registering after the first frame means the launch that started you is already gone.

It works in debug and fails in release

The generated background entrypoint carries @pragma('vm:entry-point') because nothing in Dart references it, and release builds tree-shake it away otherwise — the engine then fails to start with nothing but a bare false. If you have edited a generated file by hand, regenerate it.

Building fails on iOS 16

AppIntent is iOS 16+, but AppIntentsPackage is iOS 17+. os_intents targets 16 deliberately and does not use the latter. If you added an AppIntentsPackage of your own, that is where the deployment-target error comes from.


Android

Android is two layers and they fail differently. App shortcuts and Assistant capabilities are generated by default. AppFunctions — the headless one — is opt-in behind sync --android. Details in android.md.

No shortcut appears at all

The manifest does not point at the generated file.

dart run os_intents_cli:os_intents install --check

Android reads res/xml/os_intents_shortcuts.xml only when the launcher activity carries the matching <meta-data>. install writes it; without it the file is present, correct and never opened.

One intent has no shortcut, the others do

It has a required parameter. A tap carries no values and there is nobody to ask, so a shortcut for it would appear and then fail on use. sync says which intents this skipped and why:

note: "addTask" gets no launcher shortcut — a tap cannot supply title.

An Assistant capability is exempt: the system fills the built-in intent's parameters before launching anything.

The shortcut is labelled os_intents_addTask_label_short

The string resource did not make it into the build. ShortcutManager resolves labels through the resource table, so this is a packaging problem, and only the device can report it:

dart run os_intents_cli:os_intents doctor --device

Execution.background still opens the app

On the app-shortcuts layer it always will. A shortcuts.xml <intent> starts an Activity; there is no way to answer one without a UI, so the plugin routes the launch into the UI isolate. Headless execution is what the AppFunctions layer exists for, and it is behind sync --android.

An assistant does not offer my function

Foreground intents are deliberately absent. An AppFunctionService has no Activity to bring forward, so offering one would produce an action that always fails. doctor --android shows which functions reached the APK.

Nothing has been observed end to end here. The bridge is proven, but the path from a real assistant through AppFunctionService has never run, because Gemini's integration is in a private EAP. See verified.md.

The AppFunctions build fails

That layer forces a version chain, and os_intents will not change your build for you:

  • compileSdk = 37 and compileSdkMinor — Android 17 has minor API levels, so the platform is android-37.1 and compileSdk alone does not resolve.
  • AGP 9.1.1+, Gradle 9.3.1+, and the KSP plugin.
  • The androidx.appfunctions dependency and its compiler.
  • OsIntentsSetup.configure() from Application.onCreate.

For that last one: Flutter's manifest template already carries android:name="${applicationName}". Install a custom Application by replacing that placeholder, not by adding a second android:name — the merger fails on the duplicate with nothing more useful than a parse error.

doctor --android reports an optionality mismatch

The generated Kotlin lists every property under <required>, but androidx.appfunctions treats a nullable property as optional however it is listed. doctor reports what the runtime will enforce, not what the file says.


Build and codegen

No *.os_intents.json found under lib/

build_runner has not run, or no function carries @AppIntent. os_intents build runs it for you.

The build fails with a name in the wrong place

Messages like "Parameter … is an enum but has no enumTypeName" mean the manifest is internally inconsistent — regenerate it. This is checked rather than assumed because an unfilled type name used to be interpolated into generated Dart, Swift and Kotlin as the literal word null.

sync --check fails in CI

The generated files no longer match the manifest. Run os_intents build and commit the result. Two guards, and they catch different things:

sync --check the generated files match the manifest
install --check the native projects reference those files

My users' saved shortcuts stopped working

An intent id is the contract. It is what a saved shortcut or an automation points at, and by default it is your function's name — so renaming the function orphans everything already built on it. Pin it with @AppIntent(identifier: 'addTask'), and assert on the list in a test:

test('no handler was renamed', () {
  expect(IntentHarness($osIntentsRegistry).registeredIds,
      ['addTask', 'completeTask', 'dueToday']);
});

A parameter type is refused

The wire format carries String, int, double, bool, DateTime, a class annotated @AppEntity, and an enum annotated @AppEnum. returns: is narrower still — String, int, double, bool, DateTime — because Swift fixes perform()'s return type at compile time. Both are refused by the generator rather than compiled into native code that will not build.


Still stuck

verified.md lists what has actually been observed on a device, what only compiles, and what has never been seen at all — worth checking before assuming a fault is yours. If it is not there, open an issue with the output of os_intents doctor.