Reporting DSpace issues

If you’re new to reporting DSpace issues in general, you can find a great guide about that on the Lyrasis wiki.

Narrow down the issue

When reporting a performance issue, it’s good to start by asking yourself a couple of questions

• Affected pages
  
  • Is the problem limited to a specific page (e.g., the home page) or a type of page (e.g., all browse pages or item pages)?
• Authentication required?
  
  • Does the issue occur only after logging in, or does it also affect anonymous users?
• Trigger condition
  
  • Does the issue occur as soon as the page loads, or only after you interact with it: click a button, type in a form field?
• Reproducible on demo?
  
  • Does the issue occur only in your repository, or can it also be reproduced on demo.dspace.org?
  • If possible, provide example URLs on demo.dspace.org to help others replicate the issue under known conditions. ‍
• Unusual circumstances?
  
  • If the issue is unique to your own repository, consider if there’s something unusual about your setup.
  • For instance, an exceptionally large number of collections might cause delays or errors, particularly if a UI component is attempting to list or search through all collections.‍
• ‍Stuck loading screen?
  
  • If you see a loading screen that stays up for a very long time, does it go away when you click on it?
  • That's usually a sign that the app isn't really loading all that long, but that there’s some bug in the frontend where we don't detect that the server has responded. Clicking causes the UI re-run a number of checks, so that might cause it to notice: hey we're done loading, let's hide the loading screen

Investigate the network activity

Take a look at the network panel in your browser's developer tools to pinpoint which request is the cause of the issue

How to access the network panel

• Chrome: Ellipsis menu → More tools → Developer tools → Network
• Firefox: Hamburger menu → More tools → Web Developer Tools → Network
• Safari: Menu bar → Develop → Show Web Inspector → Network

Caption: The network panel in Chrome:

Types of request

• XMLHttpRequests (XHR)
  
  • Retrieve data from the REST API
  • Performance varies based on the content in your repository
  • Issue more likely to be unique to you
  • Start looking here
• Javascript requests (JS)
  
  • Download the code to run the UI
  • Mostly identical across repositories
  • Can indicate problems with how the app is bundled
• Initial HTML request
  
  • If this slow it indicates a problem with the server side rendering performance

The top of the network panel will have a way to filter based on the type of request. In chrome that looks like this:

What to look for

• XHR requests that are very slow, or never complete:
  
  • This can be an indication that the problem lies on the backend side
  • To test that right click that request to copy its url, and try it out directly on the HAL browser for the backend
    
    • This is usually found at https://the.repository.url/server so https://demo.dspace.org/server for example
    • If you were logged in when you experienced the issue, log in on the HAL Browser first as well
    • And then paste the link in the input field at the top left and click go.
    • If it takes as long there, it's likely a backend issue, so please report it on https://github.com/DSpace/dspace/issues

• Repeating XHR request patterns:
  
  • If you see a pattern of repeated requests in rapid succession, it’s likely a frontend bug. Report it at https://github.com/DSpace/dspace-angular/issues.

• Uncertain cases:
  
  • If no requests stand out, or you’re unsure, report the issue to the frontend repository.  If we investigate it later, and find that it should have been a backend issue we can still move it.
    

Export Network Traffic (HAR File)

• it's always useful if you include an export of your network traffic as a HAR file
  
  • Chrome: Click the download icon in the top bar of the network tab
  • Firefox: Click the gear icon in the top-left of the Network tab → Save all as HAR.**
  • Safari: Use the export button in the top bar of the network tab
• A HAR file allows us to see exactly which network requests happened, in what order, how long they took, and what the server responses contained
• It won't show us what the page looked like, where you clicked, if a content shift happened etc. But if you've followed the steps up until now you've included those already

When the whole repository is slow

Sometimes performance problems aren’t limited to specific pages but affect the entire site. In those cases the load on the node server could be the culprit

Server-Side rendering (SSR) in DSpace

• The DSpace UI uses server side rendering, mainly to ensure that crawlers from search engines can index everything without having to run javascript
• For every request that comes in, the angular server runs the javascript code needed to generate the page, does all the requests to the rest api to get the data, and returns the resulting html file
• This can be used a static file for a crawler to index
• Or for a human user, to already see the content while they're downloading the javascript code to render the rest of the application in their own browser

Performance under load

• This works fine if the both the rest angular server have plenty of resources and are not under heavy load,
• but as the load increases, the resources that the server has to spend on each request go down, and each request takes longer to process
• This is why the ability to disable SSR for certain routes was added in DSpace 8 and refined in DSpace 9. See the DSpace docs for how to configure which routes it applies to
• Keep in mind though that while disabling SSR for a lot of routes can greatly improve the performance and resource usage of your node server, it can also hurt your SEO score or block arguably legitimate use cases for bots, so keep that in mind

Conclusion

Performance issues can be frustrating, but with a structured approach, they become much easier to diagnose and resolve. By narrowing down the symptoms, investigating network activity, and providing clear reports (including HAR files when possible), you’ll significantly speed up troubleshooting, and make it easier for developers to help you effectively.

Remember: even if you’re unsure whether the issue is frontend or backend, it’s always better to report it than to leave it unresolved. The DSpace community and maintainers rely on clear, actionable feedback to continue improving the platform for everyone.