SharePoint Document Issues

How to Fix SharePoint CSOM Errors for Folders Containing # or %

Bushra Parveen Sep 29, 2026 868 views

Question details

Users encounter missing files, empty results, or invalid URL errors when using legacy CSOM URL methods to access SharePoint folders containing '#' or '%' characters.

Fix SharePoint CSOM Errors with Folders Containing # or %

Product: SharePoint
Device & OS: not provided
Scenario: Accessing, querying, or manipulating SharePoint folders and files via CSOM where the names include reserved characters.
Observed behavior: Legacy URL methods misinterpret the reserved characters (# and %), causing the code to fail with invalid URL errors, or return empty or missing file results.

Before you start

Ensure you are using an updated version of the SharePoint Client-Side Object Model (CSOM) library or SharePoint Online Management Shell that supports the newer ResourcePath API.

Solution 1Recommended

Use ResourcePath-Based Methods for Decoded URLs

Replace legacy string-based URL methods with ResourcePath APIs to safely and unambiguously handle special characters in SharePoint paths.

Legacy string-based methods in CSOM struggle with reserved URL characters. By utilizing the ResourcePath API introduced in newer SharePoint Online builds, developers can pass decoded server-relative paths directly without worrying about URL fragment encoding issues.

Identify the target folder path

Locate the exact decoded server-relative path of your SharePoint folder that contains the special characters (for example, "/sites/YourSite/Shared Documents/### Contract Review").

Update your CSOM code

Modify your script to use the ResourcePath class. Change your folder retrieval code to: var folder = context.Web.GetFolderByServerRelativePath(ResourcePath.FromDecodedUrl("/sites/YourSite/Shared Documents/### Contract Review"));

Load the folder and execute the query

Load the newly defined folder object into your context by calling context.Load(folder); and then run context.ExecuteQuery(); to successfully retrieve the data without URL encoding errors.

Use ResourcePath-Based Methods for Decoded URLs

Microsoft Solution Guidance: This approach aligns with official Microsoft solution guidance for supporting # and % in file and folder names using the ResourcePath API.

Free Microsoft Office alternative

Looking for a Hassle-Free Way to Manage Documents?

While resolving complex SharePoint APIs and development errors can be frustrating, managing your actual documents shouldn't be. WPS Office offers a free, lightweight, and highly compatible alternative to Microsoft Office for all your everyday document needs.

1. Download the Installer: Visit the official WPS Office website and download the free installation package for your operating system.
2. Install WPS Office: Run the installer file and follow the simple on-screen instructions to set up the software on your computer.
3. Open Your Office Documents: Launch WPS Office and easily open, edit, and save your existing Microsoft Office files without any compatibility issues.

Fully compatible with Microsoft Word, Excel, and PowerPoint formats.Lightweight software design for fast startup and smooth document editing.Familiar, tabbed user interface for seamless migration from Microsoft Office.Built-in cloud support for easy document sharing and collaborative management.

microsoft office alternative - wps office

Frequently Asked Questions

Why do # and % cause errors in SharePoint CSOM?

In legacy SharePoint CSOM methods and standard web protocols, '#' and '%' are treated as reserved characters for URL fragments and URL encoding. When they naturally appear in folder or file names, standard URL parsing methods misinterpret them, leading to invalid path errors or missing files.

What is ResourcePath in SharePoint?

ResourcePath is a newer API feature introduced in SharePoint Online that allows developers to pass decoded server-relative paths unambiguously. This safely supports special characters in file and folder names without triggering encoding errors.

Can I use ResourcePath on older SharePoint on-premises versions?

The ResourcePath API and the expanded support for # and % in file names were primarily introduced for SharePoint Online and later added to SharePoint Server 2016 via specific updates. Older versions of SharePoint on-premises may not support these APIs or characters.

Document & File Issues