SPFx web part works locally but fails after deployment

Zastawny Minnix 40 Reputation points
2026-11-19T00:34:10.5633333+00:00

I'm developing a custom SPFx web part that displays employee information from a SharePoint list. It works perfectly when I run it locally using gulp serve, but after deploying the .sppkg package to the App Catalog, the web part just shows a loading message. I've checked the package deployment, but haven't found anything obvious.

Microsoft 365 and Office | SharePoint | Development
0 comments No comments

Answer accepted by question author
Aetherin 4,500 Reputation points Independent Advisor
2026-11-19T01:20:56.16+00:00

Hi @Zastawny Minnix,

Thank you for checking those details. Since you are not using an external CDN and includeClientSideAssets is currently set to false, the JavaScript bundle is not being included for SharePoint-hosted deployment. This is consistent with the 404 error you found.

Please change the setting in config/package-solution.json to:

"includeClientSideAssets": true

Then rebuild and repackage the solution:

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

Upload the newly generated .sppkg file from the sharepoint/solution folder to the App Catalog, replace the existing package, and deploy it again. After that, refresh the SharePoint page and check the Network tab to confirm that the JavaScript bundle now returns 200 instead of 404.

Microsoft’s deployment guidance shows includeClientSideAssets enabled when SharePoint is used to host the solution assets: Deploy your client-side web part to a SharePoint page.

Given that the failed request is for the JavaScript bundle and returns 404, this should resolve the issue. Please redeploy the solution and let me know whether the problem persists.

Was this answer helpful?

5 people found this answer helpful.

3 additional answers

Sort by: Most helpful
  1. Aetherin 4,500 Reputation points Independent Advisor
    2026-11-19T01:06:34.1633333+00:00

    Hi @Zastawny Minnix,

    Since the web part remains stuck on the loading message, the next step is to determine whether the deployed JavaScript bundle is failing to load or whether the request to the SharePoint list is failing.

    Could you please open the deployed page, press F12, and share the exact errors shown in the Console, along with any failed requests in the Network tab? In particular, please include the request URL and HTTP status code, such as 401, 403, or 404, as well as any CORS or JavaScript errors.

    It would also help to confirm:

    • Is the employee list located on the same site as the page containing the web part?
    • Does the issue affect all users or only certain accounts?
    • Which SPFx version are you using?
    • If this is a gulp-based project, did you create the package using gulp bundle --ship and gulp package-solution --ship?
    • If you are not using an external CDN, is includeClientSideAssets set to true in config/package-solution.json?

    The Console and Network results should help distinguish between a packaging or asset-loading issue, an incorrect list URL, and a permissions issue. Once you provide those details, I can help identify the likely cause and suggest the appropriate fix.

    Looking forward to your reply. Thank you.

    Was this answer helpful?

    2 people found this answer helpful.
    0 comments No comments

  2. Zastawny Minnix 40 Reputation points
    2026-11-19T01:16:49.92+00:00

    Hi,

    Thank you for your reply. I checked the deployed page and found a 404 error for the web part’s JavaScript bundle in both the Console and Network tab.

    Additional details:

    • The list is on the same site as the web part.
    • The issue affects all users.
    • I am using SPFx 1.20.0.
    • The package was created with gulp bundle --ship and gulp package-solution --ship.
    • I am not using an external CDN.
    • In config/package-solution.json, includeClientSideAssets is set to false.

    Was this answer helpful?

    1 person found this answer helpful.
    0 comments No comments

  3. AI answer

    2026-11-19T00:34:28.52+00:00

    A common cause is that the deployed package is not loading the same assets or runtime context that worked during local debugging.

    Use this check path:

    1. Build and package for deployment.
      • Run:
             heft build --production
             heft package-solution --production
        
      • This creates the .sppkg package in sharepoint/solution.
      • With includeClientSideAssets set to true, production JavaScript, CSS, and other assets are included in the package.
    2. Verify the package was deployed correctly in the App Catalog.
      • Go to the app catalog.
      • Upload the .sppkg file.
      • Select Enable app when prompted.
      • Check the App Package Error Message column for any package issues.
      • In some deployment flows, SharePoint also shows whether the package is valid before the trust dialog appears.
    3. Confirm the solution is installed on the target site.
      • On the site where the web part should run, go to Settings > Add an app.
      • Search for the solution and install it.
      • On Site Contents, wait until installation is complete before testing the page.
    4. Check whether the deployed package is still pointing to localhost.
      • If the solution was built without --production, the generated package can reference https://localhost:4321.
      • That works only when the local development server is running.
      • A package deployed this way will fail on the site if the development environment is not running.
    5. Isolate whether this is a deployment issue or a code issue by testing with local manifests on a real SharePoint page.
      • Start the local server:
             heft start --nobrowser
        
      • Open an editable modern SharePoint page and append:
             ?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/build/manifests.js
        
      • If the web part works there, the issue is likely in packaging, deployed assets, or how the deployed bundle is being loaded.
    6. Inspect the packaged output.
      • Review the sharepoint/solution/debug folder to see the raw package contents.
      • Confirm the expected assets were packaged.
    7. If replacing an existing deployed package, upload the new package and select Replace, then Enable app.

    For the specific symptom of a web part staying on a loading message after deployment, the most relevant checks are:

    • package built with --production
    • app catalog deployment completed with no package errors
    • solution installed on the site
    • package not referencing localhost
    • packaged assets present in sharepoint/solution/debug

    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.