Table of Contents

What is the most current release of the DSpace software?

The most recent stable version of DSpace, recommended for production use, is available from GitHub.

To see what's in store for the future, see the DSpace Releases planning page and the DSpace RoadMap

Where can I download the DSpace open source software?

The most recent stable version of DSpace, recommended for production use, is freely available from GitHub.

If you are a developer, DSpace is also available to be checked out using Git/GitHub: https://github.com/DSpace/DSpace   See also Development with Git.

I have technical questions about DSpace – how can I find solutions?

You're in the right place. First, you'll want to search this FAQ to see if your question has been asked/answered already. Next, try searching the DSpace System Documentation and the DSpace-Tech mailing list archives.

Still need help?  Try our other Support options.

Is there install doc for DSpace?

Yes, the DSpace System Documentation includes a section on Installation.

If you run into any problems or have further questions, send an email to the DSpace-Tech mailing list for help, or use one of our other Support options.

How do I report bugs?

If you think you've found a bug, we recommend taking the following steps.

1. First, attempt to determine if it really is a bug by asking on the DSpace-Tech mailing list to see if others have encountered this same problem.
2. Once you've verified it with someone else, please submit a bug report to GitHub Issues. Try to be as descriptive as you can, and detail the steps that someone else would need to take to encounter this same problem.
   • Frontend (User Interface) issues: https://github.com/DSpace/dspace-angular/issues
   • Backend  (REST API) issues: https://github.com/DSpace/DSpace/issues
   • (If you aren't sure where to report it, choose either one. We can move it to a different location as needed.)
3. One of the developers will review this bug and get back to you. Don't be surprised if he/she asks some followup questions. The developer may need to figure out exactly how you encountered the bug so that he/she can figure out the best way to fix it.

Thanks for being willing to help locate and report bugs! An active community helps us make more stable, bug-free software.

How do I request new features?

Before putting in a new feature request, you should make sure that the feature would be useful to the broader DSpace community and isn't institutional specific. It's also worth mentioning that since the DSpace developers are all volunteers, you may want to work to locate an interested developer who can help you scope out and begin to develop this new feature.

If you've come up with a new feature idea, we recommend taking the following steps.

1. First, attempt to determine if this feature will be useful to everyone using DSpace. The best way to do this is to describe this feature in an email to the DSpace-Tech mailing list in order to begin the discussion.
2. Once you've determined your feature would be useful to all, please submit a feature request to GitHub Issues. Try to be as descriptive as possible. Describe the feature in as much detail as you can. Make sure to also describe why you feel this feature would be useful (i.e. what is the use case?)
   1. Frontend (User Interface) issues: https://github.com/DSpace/dspace-angular/issues
   2. Backend  (REST API) issues: https://github.com/DSpace/DSpace/issues
   3. (If you aren't sure where to report it, choose either one. We can move it to a different location as needed.)
3. Once your feature request is made, the DSpace developers will begin to review it and determine if a volunteer would step up to help developing it. Please be patient. Sometimes a volunteer can be found quickly. Other times it can take a while. If you can help us locate a volunteer developer, it is even more likely that the feature can be developed relatively quickly. If you don't hear anything for a while, follow-up with the DSpace developers by posting a comment to your initial feature request in Jira.

Also see How to Contribute to DSpace

Internal System Error: I keep receiving the message "The system has experienced an internal error". How do I diagnose the problem?

See the Troubleshoot an error page for hints on which log files to check for errors, and the recommended way of sending these to the DSpace-Tech Mailing List

What's the best strategy for backing up/restoring DSpace?

From the Documentation, see Storage Layer (which describes the basics for backing up your database and file storage). Also see AIP Backup and Restore, which describes how to backup your DSpace to a set of Archival Information Packages (AIPs).

How do I run DSpace on port 80/443?

The official Installation Documentation provides a section on "DSpace over HTTPS" which describes how to configure Apache HTTPD (responding on ports 80 and 443) to redirect to a DSpace running on Apache Tomcat.  There are many other guides out on the web for redirecting requests from Apache HTTPD (running on ports 80/443) to Apache Tomcat (usually this redirect is configured via either mod_proxy_ajp or mod_jk). Those guides should also work for DSpace, as DSpace requires no special configurations for Apache HTTPD + Apache Tomcat.

Do I need HTTPS (SSL)?

The official Installation Documentation provides a section on "DSpace over HTTPS" which describes enable HTTPS either in Tomcat directly, or in Apache HTTPD (and redirecting requests to Tomcat).

How do I run DSpace on Windows?

Use the same instructions as the Installation Documentation.  DSpace can be installed on any Operating System.  For Windows, though you may need to use backslashes (\) in paths instead of forward slashes (/).

Setting logging level up to DEBUG

See our Troubleshoot an error guide for details

I've made a lot of modifications to DSpace, and I want to bring my code up to date with a later version of DSpace. What's the easiest way to do that?

We recommend using Git's merge features to help manage this. See Development with Git for some sample workflows.

Clearing Cocoon (XMLUI) cache

Apache Cocoon, the DSpace component XMLUI is based on, keeps a cache of visited pages to speed up access to them. This can pose a problem usually during development of XMLUI themes, when you update XSL, but an older version of the page is served from cache instead of the current version being constructed. It's safe to clear the cache, the only impact it can have is on speed until the cache is repopulated.

In DSpace 1.8.0 and newer, there is a convenient link in XMLUI to clear the cache without restarting the servlet container:

1. log in as DSpace administrator
2. click on "Control Panel" in the sidebar menu
3. click on the "Java Information" tab
4. click on the "(Clear Cache Immediately)" link

Next to that link, you can also see how many pages are currently cached.

In DSpace versions up to 1.7.2, you have to clear the cache manually by shutting down Tomcat, deleting the cache directory and then restarting Tomcat:

1. ${tomcat6.home}/bin/shutdown.sh

2. cd ${tomcat6.home}/work/Catalina/{appropriate.domain.dir}/_/

3. rm -rf cache-dir

Depending on your Tomcat version, whether you used a package and where you installed it, some common locations of the cache directory are:

/var/cache/tomcat5/work/Catalina/localhost/xmlui/cache-dir
/var/lib/tomcat6/work/Catalina/localhost/_/cache-dir
/opt/tomcat6/work/Catalina/localhost/xmlui/cache-dir
/usr/local/tomcat6/work/Catalina/localhost/xmlui/cache-dir

I changed access restrictions on a collection, but restrictions didn't change on its items

You have to remember that access restrictions are inherited from its parent collection only when items are submitted, not when access restrictions are modified. So any new items submitted to that collection will have the collection's restrictions you set, but existing items will keep their current permissions.

In other words: "When a new item gets archived in the repository, it inherits the default policies for an item, defined by the collection in which the item is archived. It's important to realize that these policies can altered for each item, bundle or bitstream, without altering other items or collection properties. Policies are really tied to items, bundles and bitstreams." (source)

So how would you do a mass-change of permissions?

• In XMLUI, use Advanced Policy Manager. Log in as an administrator, in the Administrative menu, click Authorizations (under Access Control.) Then in the main pane, under the search box, there's a link to the tool (Advanced authorizations tool: Click here to go to the item wildcard policy admin tool).  See also this video guide: https://youtu.be/PFlq-yGSPY4
• You can write a curation task (see DSpace Curation System, Curation Task Cookbook)
• You can write custom SQL query on the "resourcepolicy" table.
  • In order to see this changes take effect in the UI (in Discovery search/browse), be sure to update the discovery index (using the -f flag) after running the SQL query.

How do I remove the search box from the front page in XMLUI?

This will remove the search box from the homepage body and keep the search box in the menu:

<xsl:template name="disable_front-page-search" match="dri:div[@id='aspect.discovery.SiteViewer.div.front-page-search']">
</xsl:template>

How can I change what is displayed in XMLUI for a particular collection?

If you want items in a particular collection to be rendered differently (add/remove/modify elements) than in the rest of the repository, you can use this recipe.

<xsl:variable name='mycollection'><xsl:value-of select="/dri:document/dri:meta/dri:pageMeta/dri:trail[@target='/handle/123456789/1234']"/></xsl:variable>
 
<xsl:template ...>
    ...
 
    <xsl:if test="$mycollection">
        <p>This item belongs to collection 123456789/1234.</p>
    </xsl:if>
 
    ...
</xsl:template>

I'm getting 'relation "bi_5_dis" does not exist' (or any other number)

These are the tables corresponding to individual browse indexes. Browse indexes are defined in dspace.cfg as webui.browse.index.1 through webui.browse.index.n and you can modify which metadata fields you want in the indexes, but you have to remember that after any such change, you need to re-create the indexes.

See ReIndexing Content (for Browse or Search) in the official documentation for your version of DSpace.

See also the relevant dspace.cfg section.

Duplicate items in Recent Submissions in XMLUI Discovery

This happens when you skip a step in the instructions for Discovery#EnablingDiscovery. In particular, forgetting to set  recent.submissions.count = 0 will mean that recent items continue to be rendered by the Browse aspect in addition to the Discovery aspect, resulting in duplication.

To fix this, set recent.submissions.count = 0 in [dspace]/config/dspace.cfg and restart your servlet container. If needed, also clear the Cocoon cache: TechnicalFaq#TechnicalFaq-ClearingCocoon(XMLUI)cache

How do I update Messages.properties without rebuilding DSpace?

The Messages.properties file is used for translations both in DSpace core ([dspace]/lib/dspace-api-4.0-SNAPSHOT.jar) and in DSpace JSPUI ([dspace]/webapps/jspui/WEB-INF/lib/dspace-api-4.0-SNAPSHOT.jar). You usually want to update the JSPUI one:

1. find dspace-api-X.X.jar in [dspace]/webapps/jspui/WEB-INF/lib/
2. unzip it in an external folder
3. modify the Message.properties file
4. copy Message.properties to [dspace]/webapps/jspui/WEB-INF/classes/
5. restart your servlet container 

I'm getting "SolrException: Bad Request" followed by a long query or a "tooManyClauses" Exception

From the related email thread:

The issue is related to the Access Rights Awareness feature introduced in Discovery and affect both the search and the browse system (when SolrBrowseDAO are used, optional in 3.x, by default in 4.0).
 

The issue here is that a single user is included in several groups - that means that the Solr query will include a filter to limit the results to only items that are visible by group1, group2, .... groupN.
 

• If the number of group is high, you can reach the HTTP header limit (4kB or 8kB by default, see maxHttpHeaderSize Tomcat 7 docs) or a tooManyClauses Exception in Solr, that can be "solved" incrementing this parameter: https://github.com/DSpace/DSpace/blob/dspace-4_x/dspace/solr/search/conf/solrconfig.xml#L474
• When the number is to large you could also consider to disable the Access Rights Awareness feature, commenting this line: https://github.com/DSpace/DSpace/blob/dspace-4_x/dspace/config/spring/api/discovery.xml#L25

Solutions:

in case of exceeding header size:

• increase maxHttpHeaderSize in Tomcat

in case of tooManyClauses Exception:

•  increment maxBooleanClauses; or
• disable Access Rights Awareness
  

Errors connecting to Solr

Error starting Tomcat: SEVERE: Error listenerStart

Problem: When starting Tomcat, the Tomcat log contains the following error:

Jun 01, 2016 4:41:08 PM org.apache.catalina.core.StandardContext startInternal
SEVERE: Error listenerStart

Explanation: While this may indicate various errors, one possible source of problems is re-using configuration from an older version of DSpace which is incompatible with the new code. Most likely the incompatibility is in [dspace]/config/spring/.

Solution: Move away your customized configuration directory, start again with the fresh configuration corresponding to the DSpace version you're installing or updating to and then make your changes in that configuration.

Metadata values in CSV export seem to have duplicate columns

Symptom: In a CSV export from Batch Metadata Editing, you can often see that the same column seems to be listed twice, where each of these colums contains values in different rows. The two columns may look like this: dc.title, tc.title[]

Explanation: This is a harmless inconsistency in how DSpace stores metadata. The brackets designate which language the metadata value is in (each metadata field may have multiple values in multiple languages, which is appears in the CSV like this: dc.title, dc.title[de], dc.title[en_US]). In the database, an empty language may have two representations - either an empty string "" or a special NULL value. As DSpace organically developed over time, the programmers of various data ingest methods chose one of these two representations. If you use multiple ingest methods, you may end up with metadata that use both.

Fix 1: In the CSV file, move the values from one of the columns to the other. Then import the CSV file. Upon next export, the empty column won't appear in the CSV file anymore.

Fix 2: Use the following SQL statement to fix the data: UPDATE metadatavalue SET text_lang=NULL WHERE text_lang='';

Any of these fixes will only fix your current data. If you continue to use the two different ingest methods, you'll get new such duplicates.

The permanent fix would have to fix the import methods. The JIRA issue is  Unable to locate Jira server for this macro. It may be due to Application Link configuration.