Edit

Share via

Windows AI API troubleshooting

Important

Apps using the Phi Silica APIs might encounter issues with Limited Access Feature support (see LimitedAccessFeatures).

At this time, we recommend using experimental releases as they do not require LAF tokens.

Requirements

Hardware

Phi Silica features require a Copilot+ PC (laptop keyboards have a dedicated Copilot key). See Copilot+ PCs developer guide for a list of recommended devices.

Software

Windows 11, version 25H2 (build 10.0.26200.7309) or later must be installed on the Copilot+ PC. This can be verified by opening the Start menu, typing "winver", and pressing Enter (a dialog box with the OS details, similar to the following, should appear).

Screenshot of the Windows version dialog displayed by typing 'winver', and pressing Enter.

Ensure that you can use Phi Silica features:

  1. Download and install the AI Dev Gallery app from Microsoft Store.
  2. Run the app.
  3. Select AI APIs from the left pane.
  4. Click on Phi Silica > Text Generation.
  5. Confirm that Phi Silica responds to a prompt (the sample app starts with a default prompt).

Screenshot of the AI Dev Gallery sample app showing a basic example of the Text Generation feature.

Other recommendations

Enable Developer Mode in Settings > System > For developers > Developer Mode.

Install Visual Studio with the workloads and components required for developing with WinUI and the Windows App SDK. For more details, see Required workloads and components.

Debugging

If Phi Silica does not appear to be working on your system, there are a few things you can do.

  1. Verify that you have all required models installed by going to Settings > System > AI Components, which shows the AI models available on the system. If the required model is not listed, go to Settings > Windows Update and click "Check for updates" (a restart might be required).

  2. Verify that your app is using a valid WinAppSDK minimum version.

    • Stable: 1.8.3
    • Experimental: 2.0-Exp3

  3. Check Settings > Updates to ensure Windows updates aren't paused.

  4. Collect traces through the Windows Feedback Hub app and share them with the Windows team to review.

    1. Open the Feedback Hub app (Windows key + F).
    2. Sign in with your preferred account.
    3. Enter bug details in section 1 (prefix the bug title with "[Windows AI APIs]").
    4. In section 2, click Problem, select Developer Platform from the first drop down, and then select Windows AI Foundry from the second drop down.
    5. Section 3 will display any existing feedback that is similar to yours. If existing feedback is not found, select New feedback and click Next.
    6. In section 4 you can:
      1. Click Recreate my problem, then click Start recording, run AI Dev Gallery, reproduce the issue, stop recording.
      2. Include additional info and attachments (such as images). Provide as much detail as possible, including reproduction steps and error messages.
    7. Submit the feedback.

Other guidance

  • Apps that use Windows AI APIs need to be granted package identity at runtime. For details, see Advantages and disadvantages of packaging your app. If you are seeing an UnauthorizedAccessException error (or having other access issues), ensure that your app is packaged and the systemAIModels capability was added to your manifest file (see Get started building an app with Windows AI APIs).

  • Limited Access Feature (LAF) requirements:

  • Self-contained apps cannot run from the Downloads folder (or from anywhere under the C:\Users folder). For more details, see Advantages and disadvantages of packaging your app and Windows App SDK deployment overview.

  • The Windows App SDK experimental channel includes APIs and features in early stages of development. All APIs in the experimental channel are subject to extensive revisions and breaking changes and may be removed from subsequent releases at any time. Experimental features are not supported for use in production environments and apps that use them cannot be published to the Microsoft Store.

  • Provide feedback on these APIs and their functionality by creating a new Issue in the Windows App SDK GitHub repo (include Phi Silica in the title) or by responding to an existing issue.

See also

  • Last updated on