Troubleshooting Shortcuts AI
Fix common setup, setup key, Share Sheet, permission, tool, billing, and Agent session problems.
Start by running Agent once from the Shortcuts app. A direct run helps separate an Agent problem from a Siri, Share Sheet, Action Button, or widget problem.
Shortcuts did not open during setup
Return to the Shortcuts AI setup page on your iPhone and tap Continue Setup again. The button copies your setup key before opening Apple Shortcuts.
If the automatic handoff still fails:
- Use Copy key on the setup page.
- Choose the manual installation option shown on that page.
- Paste the copied key when Apple Shortcuts asks for it.
- Tap Add Shortcut.
Do not paste a shortened or partially hidden version of the key.
The setup key or authentication failed
Your setup key connects the shared Agent shortcut to your account. If Agent reports an authentication problem, return to the setup page, choose Repair pairing, and repeat the installation steps with the key currently shown there.
If you copied the key through a message or note, copy it directly from the setup page instead. Keep the key private.
Agent is missing from the Share Sheet
First confirm that the content you are sharing is a supported input, such as text, a link, a Safari page, an image, audio, a PDF, or another file.
Then open Agent in the Shortcuts app, open the shortcut details, and confirm that Show in Share Sheet is enabled. Apps can hide shortcuts when the selected content does not match the shortcut's accepted input types.
You can still open Shortcuts and run Agent directly when an app does not provide suitable Share Sheet input.
Siri, the Action Button, or a widget does not start Agent
Run Agent directly from Shortcuts first. If that works, check the entry point:
- Siri: say the shortcut's exact name. Rename it to a short, distinct phrase if Siri regularly chooses something else.
- Action Button: confirm the button is assigned to the Agent shortcut.
- Widget: edit the Shortcuts widget and select Agent, or select the folder that contains it.
Entry-point options vary by iPhone model and operating-system version.
An app asks for permission or an action fails
Apple Shortcuts and the app performing the action control local permissions. Review the prompt and allow only the access you want to grant.
If you previously denied access, review the relevant app, Shortcuts, or privacy permission in iPhone Settings, then run the request again. Shortcuts AI cannot override a device permission.
An action can also fail when the required app is not installed or the device does not support it. Check Tools and device actions for the tool's app and device requirements.
Agent cannot use a tool
Open Settings → Tools and confirm that the tool is enabled. Enabling a tool makes it available to Agent, but the request still needs to make the intended action clear.
For example, "Tell Jamie about the meeting" does not say whether to use Messages, Mail, Gmail, or Outlook. Name the app or action when the choice matters.
A file or audio request fails
Keep your iPhone online while Agent uploads a selected file or transcribes audio. Confirm that you shared the intended item and that Agent received it as Shortcut Input.
If the request fails, run Agent again from the Share Sheet with only the file you need. Do not close the shortcut while an upload or transcription is still in progress.
Audio transcription is an online, billable tool. See Usage pricing.
Agent says credits are required
Open Settings → Billing to review the balance and add credits if you want to continue. A new paid session cannot start when the available balance does not meet the service requirement.
See Usage pricing for how model and online-tool usage is charged.
A session stops or keeps waiting
Try the request again as a new Agent run. A session can stop when its online workflow is no longer active, an earlier action did not return the expected result, or a temporary provider or network error occurs.
If Agent offers to prepare a support email, keep the session ID in the draft. It helps the support team find the failed session.
Contact support
Email support@getshortcuts.ai and include:
- what you asked Agent to do;
- where you started it, such as Shortcuts or the Share Sheet;
- the app or tool involved;
- the error message and session ID, if shown; and
- your iPhone model and operating-system version.
Never include your setup key in a support email or screenshot.