Structure Plugin for JIRA - Version 1.7

Index

Child pages
  • Troubleshooting Database

This documentation relates to an older version 1.7 of the Structure Plugin for JIRA. View the current documentation home.

Skip to end of metadata
Go to start of metadata

Structure Plugin uses embedded Apache Derby database to store its data. The database files are located in JIRA home directory and are crucial for the plugin operation.

1. Database Check

If you suspect that Structure's database may have failed, please go through the following check list before calling in support. Usually it's one of those problems.

For brevity, we'll use Unix-like path names with "/" as the separator. On Windows, the path names are delimited with "\". We'll also write $JIRA_HOME to refer to the JIRA home directory.

  • Is there enough disk space on the file system that contains $JIRA_HOME and $JIRA_HOME/structure/db?
  • Does the user account, under which JIRA process is running, have full access to all the content of $JIRA_HOME/structure?
    • Check file and directory ownership
    • Check file and directory permissions
    • JIRA must be able to read/write files, create files, delete files. Full access.
  • Is file system that hosts $JIRA_HOME/structure mounted read-write?
    • Try creating a dummy file in $JIRA_HOME/structure.
  • Do you not have any other applications that might access this JIRA's $JIRA_HOME/structure and lock it?
    • For example, aren't you running two JIRA instances on the same JIRA home?

2. Symptoms of Database Problems

2.1. Structure Plugin fails to start, gets Disabled

Observation: You start JIRA or enable Structure Plugin, but it immediately gets disabled.

Explanation: Structure shuts down and disables itself if it cannot properly start the database. Check the server logs for the following message:

Structure Plugin failed to start its database and will be DISABLED in a few seconds.
...
====================================================================================
Structure Plugin failed to start and was automatically DISABLED.
Error message: ....

Please fix the problem and enable the plugin again through the Plugin Manager.
If the problem persists, please contact support.
====================================================================================

2.2. The users cannot make any changes in Structure, getting errors

Observation: The structure is displayed correctly in the browser, but any attempt to change the hierarchy results in red error messages at the bottom of the screen, saying there was a problem on the server.

Explanation: It is possible that the database has shut down or become read-only due to one of the reasons mentioned above. Since Structure has some information in the server-side cache, it still can serve certain requests.

Check the logs for the following message:

==================================================
Structure Plugin storage problem: ....
==================================================

3. Proposed course of actions

  1. Go through the checklist above to locate the problem with the database. If needed, request support from support@almworks.com
  2. When the problem is cured, try disabling the plugin (if it's not disabled yet) and enabling it back again.
  3. If that does not help, try restarting JIRA.