Troubleshooting search issues in Bitbucket Data Center
Introduction
In Bitbucket Data Center, users may encounter issues where the code search does not return the expected results for a specific repository. This document provides a structured approach to troubleshooting these search issues, focusing on the new Search index insights feature available under repository settings.
Diagnosing search issues
If you notice that a search does not return the expected results, the first step is to verify the search indexing status of your repository. To do this, go to the Search indexing page within your repository settings. This page is available to users who have repository admin (REPO_ADMIN) permissions and offers essential information regarding the indexing status of the repository.
Exploring the search indexing page
On the Search indexing page, you’ll find several important details:
Status: Displays the current indexing status with a lozenge indicator.
Last indexed commit: This shows the commit hash that was last indexed.
Last indexed time: Indicates the last time the repository was indexed.
Error: If the status is FAILED, an error message or stack trace will explain the cause of the failure
Indexing status codes
COMPLETED: The repository content is indexed and synchronized with the repository on disk.
FAILED: The repository encountered problems during indexing and has been removed from the queue.
IN QUEUE: The repository content is out of sync, but changes are queued for indexing.
NOT INDEXED: The repository content is not synchronized and not queued for processing.
UNKNOWN: The indexing status could not be determined.
Addressing a FAILED status
If the status is FAILED, review the error message for insights into the indexing issue. Repository admins often need to collaborate with system administrators (SYS_ADMIN) to delve into system logs for a deeper understanding of the failure.
Reindexing a single repository
System admins can attempt to reindex the repository using the following curl command:
curl -u <USERNAME> \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
<BITBUCKET_URL>/rest/indexing/latest/projects/<PROJECT_KEY>/repos/<REPO_SLUG>/syncMake sure to replace <USERNAME>, <BITBUCKET_URL>, <PROJECT_KEY>, and <REPO_SLUG> with the specific values for your environment.
Reindexing multiple repositories
If multiple repositories require reindexing, system admins can use the following endpoint. This allows you to reindex multiple repositories in one request by specifying an array of objects containing the projectKey and slug for each repository:
curl -u <USERNAME> \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '[
{"projectKey": "<PROJECT_KEY_1>", "slug": "<REPO_SLUG_1>"},
{"projectKey": "<PROJECT_KEY_2>", "slug": "<REPO_SLUG_2>"}
]' \
<BITBUCKET_URL>/rest/indexing/latest/reindexReplace <USERNAME>, <BITBUCKET_URL>, <PROJECT_KEY_1>, <REPO_SLUG_1>, <PROJECT_KEY_2>, and <REPO_SLUG_2> with the appropriate values for your setup.
Evaluating the indexing thread
Understanding the state of the search indexing thread is also crucial. System admins can assess the thread's health using this curl command:
curl -u <USERNAME> \
-X GET \
-H 'Accept: application/json' \
<BITBUCKET_URL>/rest/indexing/latest/support-info/indexing-thread-snapshotThis provides a snapshot of the indexing thread's status. The thread can be in various states, such as:
BROKEN: The thread is active but cannot continue processing due to an error.
IDLE: The thread is active but idle, as no items are in the queue to process.
PROCESSING: The thread is actively processing items from the queue.
STOPPED: The thread is no longer active.
UNKNOWN: The state of the thread cannot be determined.
Restarting the indexing thread
In cases where the thread is BROKEN or STOPPED, restarting it might resolve the issue. Use the following curl command to restart the thread:
curl -u <USERNAME> \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
<BITBUCKET_URL>/rest/indexing/latest/restartEnsure that <USERNAME> and <BITBUCKET_URL> are replaced with your credentials and server URL.
Additional resources
Refer to the Bitbucket Data Center REST API documentation for a complete list of Bitbucket search indexing REST APIs.