Troubleshooting

This article reviews helpful debug endpoints you can use to investigate indexing API issues. For a comprehensive document on the different endpoints available for debugging, please review this troubleshooting document. If you require further assistance debugging, the Next Steps section describes what information to share with Glean Support when raising a ticket.

In the examples below, copy your full backend URL from app.glean.com/admin/about-glean under Server instance (QE), and replace https://tenant_id-be.glean.com with it.

Debug Connector Status

Documentation Link

curl -i -X POST \
  'https://tenant_id-be.glean.com/api/index/v1/debug/{connector}/status' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

When to Use

If you want to confirm whether your indexing job was successful, you can use this endpoint to verify if your documents have been uploaded and indexed. The bulkUploadHistory will show the details of your document indexing endpoint time. After documents are uploaded, they will be queued for processing. New documents will be available in search results when the processingHistory timestamp is after the bulkUploadHistory.

Debug Connector Document

Documentation Link

curl -i -X POST \
  'https://tenant_id-be.glean.com/api/index/v1/debug/{connector}/document' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -d '{
    "objectType": "Article",
    "docId": "art123"
  }'

When to Use

If a user reports a missing document, this endpoint can be used to confirm if a document is present in the connector index and verify what permissions this document has. A user will be able to view a document if any of the below criteria is met:

• allowAnonymousAccess is true
• allowAllDatasourceUsersAccess is true and user has been indexed as a user of the connector
• user is a member of the allowedGroups and in the list of allowedUsers OR allowedGroupIntersections

Debug Connector User

Documentation Link

curl -i -X POST \
  'https://tenant_id-be.glean.com/api/index/v1/debug/{connector}/user' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -d '{
    "email": "u1@foo.com"
  }'

When to Use

This endpoint can be used along with debug connector document to confirm if a user is in the group(s) provisioned to have access to the document.

Check Document Access

Documentation Link

curl -i -X POST \
  https://tenant_id-be.glean.com/api/index/v1/checkdocumentaccess \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "datasource": "string",
    "objectType": "string",
    "docId": "string",
    "userEmail": "string"
  }'

When to Use

To check if a user has access to view a document in Glean. The response will show true or false. If false, review the debug endpoints debug connector user and debug connector document to check permissions.

User and Membership Ingestion

Custom datasource user uploads can appear to succeed — with bulkUploadHistory showing UPLOAD COMPLETED — while indexed user counts remain far below what you expect. This is usually caused by confusion between the upload, processing, and indexing stages of the pipeline.

Understand the upload pipeline

User and membership ingestion follows a three-stage process:

Stage	What happens	How to check
Upload	The API accepts the payload and queues it for processing. bulkUploadHistory shows processingState: UPLOAD COMPLETED.	Check identity.users.bulkUploadHistory in the connector status endpoint.
Processing	Glean expands derived groups and memberships. This step associates users with the groups and permissions needed for document access.	Check identity.processingHistory for timestamps.
Indexing	Users become searchable and their permissions are applied to documents.	Check identity.users.counts.uploaded vs the document-level counts.indexed for user-type objects.

note

UPLOAD COMPLETED only means the API accepted your upload. It doesn't mean users are indexed and searchable. Always check counts.indexed or the debug user endpoint to confirm users are fully processed.

Trigger membership reprocessing

If counts.indexed is lower than expected after uploads show UPLOAD COMPLETED, trigger membership reprocessing to re-expand derived groups and memberships:

curl -i -X POST \
  'https://tenant_id-be.glean.com/api/index/v1/processallmemberships' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

When to Use

Call this endpoint when uploaded user counts don't match indexed counts, or when you've updated group memberships and need Glean to re-derive permissions. After triggering, allow time for processing to complete before re-checking counts.

Debugging checklist

If users aren't appearing as expected after a bulk upload, follow these steps:

1. Check upload status — call the connector status endpoint and confirm that identity.users.bulkUploadHistory shows processingState: UPLOAD COMPLETED and status: SUCCESSFUL.
2. Compare uploaded vs indexed counts — in the same response, compare identity.users.counts.uploaded with the indexed counts. If indexed is much lower, the processing step may not have completed.
3. Trigger reprocessing — call /processallmemberships to trigger membership expansion.
4. Wait and re-check — allow several minutes for processing, then call the status endpoint again to check whether counts.indexed has increased.
5. Inspect individual users — use the debug user endpoint with a specific user's email to check their uploadStatus, isActiveUser, and uploadedGroups. If uploadedGroups is empty, the user was uploaded but not yet associated with any groups.
6. Check your upload payload — verify that your /bulkindexusers or /bulkindexmemberships payloads include the correct isFirstPage, isLastPage, and uploadId pagination flags. Incorrect pagination can cause partial uploads to be treated as complete.

Custom property validation errors

When a document pushed via /indexdocument or /bulkindexdocuments contains a custom property value that violates its declared type, the API returns an HTTP 400 response that identifies the specific document and offending value.

Example error response

A document with a TEXTLIST custom property that contains a non-string element produces an error like:

Document rightanswers-doc-001 has invalid value at index 2
for custom property Attributes: expected String, got java.lang.Integer

The response includes:

Detail	Description
Document ID	The ID of the document that failed validation. If the document ID is missing or null, this renders as Document (id unspecified).
List index	For list-type properties (TEXTLIST), the index (starting from 0) of the offending element.
Property name	The custom property whose type constraint was violated.
Expected vs actual type	The declared type (for example, String) compared to the runtime type of the value that was provided. For non-list properties, the message reads: expected String, Number, or list of strings, got <type>.

Debugging checklist

If a bulk upload fails with a 400 validation error for custom properties, follow these steps:

1. Read the response body: the error message names the document ID, property, and value that caused the failure.
2. Locate the document in your upload payload: search for the document ID to find the record with the invalid value.
3. Check the offending property value: for list-type properties, use the list index from the error to find the exact element. Verify that every element in the list matches the declared type.
4. Fix and re-upload: correct the value and resubmit the request. Validation fails fast on the first invalid property, so repeat until the upload succeeds.

note

Validation stops at the first invalid custom property it encounters. After fixing one error, re-upload to check for additional issues in other documents or properties.

Next Steps

info

If you need help debugging your issue, please contact Support and provide the following details:

• Description of the issue including error message
• Endpoint URL and request body schema
• Connector name
• Timestamp/timezone of when you encountered the error