“Custom web part error” – Custom web part fails to load or render.

When a Custom Web Part fails to load or render in SharePoint, it can be due to various reasons such as incorrect configuration, missing dependencies, coding errors, permission issues, or server-side problems. Below, I provide a detailed, step-by-step guide to troubleshooting and resolving the issue.

---

1. Understand the Error Message

Before jumping into troubleshooting, examine the error message carefully. SharePoint usually provides details about why the web part is not loading. The error could be:

• Something went wrong
• Custom web part cannot be loaded
• Unexpected error occurred
• Correlation ID provided

How to check error details?

1. Edit the SharePoint page:
   • Navigate to the SharePoint page where the web part is failing.
   • Click on the settings gear (⚙️) and select Edit Page.
   • If the web part is broken, you will see an error message.
   • Click on More Details (if available) to get specific error logs.
2. Use the Developer Console (F12 in Browser):
   • Open Google Chrome or Microsoft Edge.
   • Press F12 or right-click and select Inspect.
   • Go to the Console tab to check if there are any JavaScript errors.
   • Go to the Network tab and check if any files are failing to load.
3. Check SharePoint Logs with Correlation ID:
   • If SharePoint provides a Correlation ID, use the ULS Logs to find more details.
   • Run the following PowerShell command on the SharePoint server: Get-SPLogEvent | Where-Object {$_.Correlation -eq "<your-correlation-id>"} | Format-List

---

2. Check Web Part Installation & Deployment

Your SPFx (SharePoint Framework) or Custom Web Part might not be deployed correctly. Follow these steps:

For SPFx Web Parts (Modern SharePoint)

1. Ensure the Web Part is deployed properly:
   • Open the SharePoint App Catalog (https://yourdomain.sharepoint.com/sites/appcatalog).
   • Go to Apps for SharePoint.
   • Check if your custom web part solution (.sppkg file) is available.
   • If not, redeploy it:
     • Open PowerShell.
     • Navigate to your SPFx project folder.
     • Run: gulp clean gulp bundle --ship gulp package-solution --ship
     • Upload the new .sppkg file to the App Catalog.
2. Check Site Collection App Catalog:
   • If using a site collection-based app catalog, make sure the solution is installed there.
3. Confirm the Web Part is Available in the Toolbox:
   • Edit the page and click + Add a Web Part.
   • Search for the web part in the toolbox.

---

For Classic Web Parts (Server-Side)

1. Verify the Web Part is Installed:
   • Go to Site Settings > Web Parts and check if the web part is listed.
   • If missing, redeploy the .wsp solution: Add-SPSolution -LiteralPath "C:\PathToSolution\YourWebPart.wsp" Install-SPSolution -Identity YourWebPart.wsp -GACDeployment
   • Activate the feature in Site Collection Features.
2. Check Web.Config for SafeControls (For Farm Solutions):
   • Open web.config on the SharePoint Web Front End (WFE) Server.
   • Ensure the custom web part is listed under <SafeControls>.

---

3. Check Permissions

Permissions can prevent the web part from loading.

1. Ensure the User Has Access to the Web Part Files:
   • If using SPFx, make sure users have read access to the deployed assets in CDN or SharePoint library.
   • If server-side, check the solution files in C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\16\TEMPLATE\LAYOUTS.
2. Grant Permissions Using PowerShell (For Classic Web Parts):
   • Run: Add-SPShellAdmin -UserName "DOMAIN\User"
3. Check API Permissions (For SPFx Web Parts Using APIs):
   • Go to SharePoint Admin Center (https://admin.microsoft.com).
   • Under API Management, check if all required permissions are granted.

---

4. Debugging the Web Part Code

If the web part is failing due to JavaScript or API issues, follow these steps:

For SPFx Web Parts

1. Run Locally for Debugging:
   • Navigate to your SPFx project folder.
   • Run: gulp serve
   • Open https://yourdomain.sharepoint.com/sites/YourSite/_layouts/15/workbench.aspx.
   • Check for errors in Developer Console (F12).
2. Check for Missing Dependencies:
   • Open package.json and verify required dependencies.
   • Run: npm install

For Classic Server-Side Web Parts

1. Check Web Part Properties:
   • Edit the page, go to Web Part Properties, and check if the properties are correct.
2. Review the Web Part Code:
   • Ensure there are no null references in the RenderWebPart function.

---

5. Check SharePoint Online Throttling (For SPFx Web Parts)

If your web part calls SharePoint APIs frequently, Microsoft 365 may throttle it.

1. Check API Usage:
   • Run: Get-PnPUnifiedAuditLog -StartDate (Get-Date).AddDays(-1) -EndDate (Get-Date) | Select-String "throttled"
2. Reduce API Calls:
   • Use batching to minimize requests.
   • Cache data where possible.

---

6. Reset and Re-add the Web Part

If everything else fails:

1. Remove the web part:
   • Edit the page.
   • Delete the faulty web part.
2. Re-add the web part:
   • Click + Add Web Part.
   • Search for your custom web part and add it again.

---

7. Contact Microsoft Support

If you still can’t resolve the issue:

• Open a Microsoft Support Ticket through the Microsoft 365 Admin Center.

---