How to Fix Issues with Apple's AppIntents Framework?

loading views

I recently started to migrate Futureland's iOS/macOS shortcut actions to the new AppIntents framework Apple released with iOS 16.

First of all, the Apple team did an amazing job designing this framework. It doesn't require a lot of boilerplate and is extremely flexible. I had a lot of fun developing new shortcuts with it, until I noticed that it's pretty hard to debug.

The first issue I noticed is, that the new and migrated shortcut actions I created didn't show up in the shortcuts app in my simulator. There is no warning and there is no error shown in Xcode, so why couldn't I find them in the shortcuts app?

After hours of debugging and searching the web I found this tweet, which suggested to export and search the build logs to find more information.

If you have troubles with your shortcuts and it feels like they don't correctly show up, even if they should and you got no warning or error message this is the place to look. Search for AppIntents and you will find related warnings (that are actually errors) that don't show up in Xcode.

2023-04-18 10:05:19.887 appintentsmetadataprocessor[15198:6671970] Starting appintentsmetadataprocessor export
2023-04-18 10:05:20.396 appintentsmetadataprocessor[15198:6671970] warning: At least one halting error produced during export. No AppIntents metadata have been exported and this target is not usable with AppIntents until errors are resolved.
2023-04-18 10:05:20.396 appintentsmetadataprocessor[15198:6671970] warning: Unable to map action parameter of AppIntents.IntentParameter<Swift.Optional<Futureland.Journal>> to a valueType

Look at the following warning:

At least one halting error produced during export. No AppIntents metadata have been exported and this target is not usable with AppIntents until errors are resolved.

When there is only one thing wrong with any of your AppIntents, Xcode won't include them in the build without giving any warning in Xcode.

The warning Unable to map action parameter of AppIntents.IntentParameter<Swift.Optional<Futureland.Journal>> to a valueType isn't that helpful in terms of actionability, but it pointed me in the right direction to fix the issue. Imagine debugging AppIntents, without seeing these kind of errors.

After you fixed everything the AppIntents will correctly get built and will be included in the shortcuts app the next time you start it. The build log will then look something like this:

2023-04-18 14:15:53.123 appintentsmetadataprocessor[30970:6995835] Starting appintentsmetadataprocessor export
2023-04-18 14:15:53.666 appintentsmetadataprocessor[30970:6995835] Writing Metadata.appintents
2023-04-18 14:15:53.668 appintentsmetadataprocessor[30970:6995835] Metadata root: /Users/lucas/Library/Developer/Xcode/DerivedData/Futureland-afjzcpcdkaorkjeljkrogqxwphjm/Build/Products/Debug-iphonesimulator/Futureland.app/Metadata.appintents
2023-04-18 14:15:53.682 appintentsmetadataprocessor[30970:6995835] Writing ExtractedAppShortcutsMetadata.stringsdata file
2023-04-18 14:15:53.684 appintentsmetadataprocessor[30970:6995835] Writing ExtractedParameterSummaryMetadata.stringsdata file

Alternatively you can expand the build log in Xcode where it says something like Extract app intents metadata in x seconds. Careful! The green checkmark will also show when there are warnings and the app intents were not included in the build.