Fixing the "Part URI Not Valid" Error in SPFx

One such error that can be particularly confusing is: "Invalid SharePoint App package, Error: Part URI is not valid per rules defined in the Open Packaging Conventions Specification." In this blog, we’ll dive into the details of the issue, its root cause, and the steps to resolve it.

Resolving the SPFx Error: Part URI is not valid per the rules defined in the Open Packaging Conventions Specification

When working on SharePoint Framework (SPFx) solutions, developers may occasionally encounter unexpected errors during the packaging and deployment process. One such error, often seen when uploading an ".sppkg" file to the SharePoint App Catalog, is:

"Invalid SharePoint App package, ErrorL Part URI is not valid per rules defined in the Open Packaging Conventions Specificaiton".

If you have run into this issue, don't worry - this guide will help you understand the root cause and provide step-by-step instructions to resolve it efficiently.

Introduction

Recently, while updating an SPFx web part retrieved from GitHub to meet project requirements or creating a new project, I encountered this error when attempting to upload the ".sppkg" package to the SharePoint App Catalog. Despite the web part functioning correctly and the package creation process completing without issues, the error persisted. Here's how I resolved it.

Scenario

While working on an SPFx project, you might follow a common development workflow:

1. Download an SPFx web part solution from GitHub or create a new project.
2. Modify the code to align with your project requirements.
3. Run the following commands to clean, bundle, and package the solution:

   gulp clean
   gulp bundle --ship
   gulp package-solution --ship

4. Attempted to upload the ".sppkg" file to the SharePoint App Catalog.

Despite the package being created successfully, the upload may fail, displaying the error as shown in the image below.

Troubleshooting Attempts That Didn't work

Before identifying the root cause, I tried the following common troubleshooting steps:

• Updating npm packages.
• Reinstalling dependencies.
• Changing the version of "@microsoft/sharepint-generator".

Unfortunately, none of these solutions resolved the issue.

Root Cause

After extensive research, I discovered that the problem stems from the naming convention of the parent folder containing the SPFx solution. If the folder name incudes spaces, underscores, or special characters (such as dashes), it violates the Open Packaging Conventions Specification, leading to this error.

For example, consider the following project path:

D:\Parth\Projects\SharePoint Hub Connector

Here, the parent folder name "SharePoint Hub Connector" contains spaces, which triggers the issue.

Solution: Renaming the Parent Folder

To resolve this error, follow these steps

1. Close your code editor (e.g., Visual Studio Code) to ensure no files are in use.
2. Rename the parent folder to remove spaces, underscores, or dashes. For example:
   • Incorrect: "SharePoint Hub Connector"
   • Correct: "SharePointHubConnector"
3. Reopen the project in your code editor.

4. Run the build commands again to regenerate the package.

   gulp clean
   gulp bundle --ship
   gulp package-solution --ship

5. Navigate to the sharepoint/solution folder and locate the new ".sppkg" file.
6. Upload the updated package to the SharePoint App Catalog.

By following these steps, the error should no longer appear, and your package should upload successfully.

Detailed Step-by-Step Guide

1. Close all open instances of your code editor (e.g., Visual Studio Code).
2. Navigate to the directory containing your SPFx project.
3. Check the name of the parent folder and remove any spaces, underscores, or special characters.
4. Reopen the folder in your code editor.
5. Open the terminal and execute the following commands:

   gulp clean
   gulp bundle --ship
   gulp package-solution --ship

6. Locate the .sppkg file inside the sharepoint/solution directory.
7. Upload the .sppkg file to the SharePoint App Catalog.

Conclusion

This error is common among SPFx developers, especially when working with solutions retrieved from external sources like GitHub. Ensuring that the parent folder name follows proper naming conventions—without spaces, underscores, or special characters—can prevent this issue.

If you continue to face problems, double-check your folder structure and confirm that all dependencies are correctly installed.

I hope this guide helps you quickly resolve the "Part URI is not valid" error in SPFx solutions.