Using the database integrity checker
Searching for common data inconsistencies, the Database Integrity Checker attempts to ensure that all Jira data is in a consistent state.
This is useful in a number of situations, for example:
- Before migrating a project to a new workflow
- An external program is modifying Jira's database
- Troubleshooting a server crash
If an error is encountered, most of the integrity checks provide a 'repair' option that attempts to reset the data to a stable state.
For all of the following procedures, you must be logged in as a user with the Jira system administrator global permissions.
Skip to:
- Using the Integrity Checker
- Audit events
- Overview of the integrity checks
- Integrity Checker property keys
Using the Integrity Checker
- From the top navigation bar select Administration
> System. - Select System support > Integrity checker to open the Integrity checker page.
The integrity checker has a number of integrity checks that look for common inconsistencies in Jira's stored data. Explore integrity checks in details
- Select one or more options you would like to run and select the Check button.
- While the checks are running, you can track the status of the operation in the progress bar. When the operation is complete, select the Acknowledge button.
The preview screen will display to show you if all the checks have passed.
If any data inconsistencies are found, they'll display in red and the Fix button will also appear on the page. To fix the incosistencies, select the check for which they appear and select the Fix button.
Messages in yellow are warnings that the check won't correct. Jira will auto-recover from these inconsistencies when an action is taken on an issue.
We strongly recommend taking a backup of your data before correcting any data inconsistencies.
- If any inconsistencies were found and you chose to correct them, you will be presented with a summary screen describing all the corrective actions that have taken place.
Integrity Checker will display the number of records that is limited by the jira.integrity.checker.displayable.results.limit property. This means, if the limit is set to 20, each check will display a maximum of 20 results.
Integrity Checker will also fix the number of affected records that is limited by the jira.integrity.checker.results.limit property. This means, if the limit is set to 1000, a maximum of 1000 records will be fixed. If 2000 affected records are found, you may proceed to fix 1000 records only and run the check again or adjust the limit to address more records.
Audit events
There are three types of audit events related to Integrity Checker:
Integrity checker task started, when check or fix starts.
Integrity checker task finished, when check or fix is finished and acknowledged by the person who runs the operation.
Integrity checker task removed, when one system admin ran a check or fix, it finished, but:
it wasn't acknowledged by the submitter. If this happens, the submitter can find it back in the audit log, use the Progress URL to return to the page, and acknowledge the task.
the node of task submission was restarted and another system admin entered the
https://{JIRA_HOME}/secure/admin/IntegrityChecker!default.jspa. If this happens, the task can’t be acknowledged anymore. To solve it, run the check or fix again.
Overview of the integrity checks
The integrity checker has a number of integrity checks that look for common inconsistencies in Jira's stored data.
| Check name | Is it a long-running fix? | What it checks | How it fixes |
|---|---|---|---|
| Check Issue Relations | |||
| Check Issue for Relation 'ParentProject' | Yes | Checks if the Project ID on the Issue points to an existing project. | Deletes the issue if it has no corresponding project. Particularly deletes:
It's being deindexed and the delete event is being sent.
|
Check Issue for Relation 'RelatedOSWorkflowEntry' | Yes | Checks if the Workflow ID on the issue points to an existing OS Workflow Entry. |
|
Check that all Issue Links are associated with valid issues | No | Checks if the source or destination issue ID in the Issue Link points to an existing issue. | Deletes the broken Issue Link from the database. |
| Check Search Request | |||
Check search request references a valid project | Yes | Checks if the Search Request (Search Filter) with a non-empty Project field points to an existing project. |
|
| Check for Duplicate Permissions | |||
Check the permissions aren't duplicated | Yes | Checks if there are records in the
|
|
Check Workflow Integrity | |||
Check workflow entry states are correct | No | Checks if there is an Issue that has a corresponding OS Workflow Entry ID with a Status equal to | For found Issues, sets the corresponding OS Workflow Entry State to |
Check workflow current step entries | No | Checks if the Issue’s current status in the workflow is correct.
| Depending on the case, it can or can’t be fixed. |
Case 1: The Issue’s Status is null. Result: This Check can't be fixed. Use Check Jira issues with null status to recover. | |||
Case 2: The Issue’s OS Workflow Status ID is null. Result: This Check can't be fixed. Use Check Issue for Relation 'RelatedOSWorkflowEntry' to recover. | |||
Case 3: The Issue has the Status set, but there is no linked Step descriptor for this Status in its workflow. Result: This Check can't be fixed. | |||
Case 4: We found 0 records in the OS Current Step table for the Issue with the given OS Workflow Entry ID. Result: Creates a missing OS Current Step for given Issue ID with a given Status and OS Workflow Entry ID. | |||
Case 5: We found 1 record in the OS Current Step table for the Issue with the given OS Workflow Entry ID, but the Step ID is null or differs from the one mapped from the Issue Status. Result: If the OS Current Step record found is invalid, sets its value in the DB. Otherwise, skips it. | |||
Case 6: We found 1+ records in the OS Current Step table for the Issue with the given OS Workflow Entry ID. Result: Deletes redundant steps and keeps only one. | |||
Check Jira issues with null status | No | If the Issue’s Status is null |
|
Check Field Layout Scheme Integrity | |||
Check field layout schemes for references to deleted custom fields | No | Checks if all Field Layout Items are pointing to an existing Custom Field.
| Deletes the faulty record from the Field Layout Item table. |
Check for invalid filter subscriptions | |||
Check FilterSubscriptions for references to non-existent scheduled job | No | Checks if a Filter Subscription is linked to a Scheduled Clustered Job that doesn't exist in the Clustered Job table. | Delete the faulty record from the Filter Subscription table. |
Check FilterSubscriptions for references to non-existent SearchRequests | No | Checks if:
|
|
This action doesn't remove attachments stored on disk or 
Field Layout Item can specify if a given Custom Field is required in a given Field Layout. Integrity Checker property keys
Integrity Checker uses the following application property keys that you can adjust any moment in the System > Advanced properties or by using REST API.
| Property key | Description | Default value | Adjustable in Advanced properties | Adjustable via REST API |
|---|---|---|---|---|
| Maximum number of fixes to process if the Check is marked as a long-running fix. | 1000 | Yes | Yes |
| Batch size for workflow current step integrity checker. | 1000 | Yes | No |
| Maximum number of results listed in UI for a single integrity check. | 20 | Yes | No |