When working with JQL, you may encounter issues that prevent your queries from executing successfully. This section provides tips for diagnosing and resolving some of the most common issues you might face.

1. Invalid Query Syntax

Symptoms:

• You receive a 400 Bad Request error with a message indicating an invalid query syntax.

Possible Causes:

• Incorrect JSON formatting, such as missing commas, brackets, or quotation marks.
• Use of unsupported or incorrect data types for specific fields.
• Typographical errors in field names or reserved keywords.

Resolution:

• Carefully review your query for syntax errors. Tools like JSON validators can help ensure your JSON structure is correct.
• Double-check field names and data types against the JQL documentation to ensure accuracy.
• If you're unsure about the correct syntax, refer to example queries provided in the documentation.

Example Error Message:

"errorMessage": "Invalid query syntax in 'filter' field"

2. Authentication Issues

Symptoms:

• You receive a 401 Unauthorized error indicating authentication failure.

Possible Causes:

• Missing or incorrect authentication credentials, such as JWT tokens, session data, or API keys.
• Expired authentication tokens.
• Incorrect configuration of the authentication method in the __meta__ object.

Resolution:

• Ensure that your authentication credentials are valid and included in the query's __meta__ object.
• If using JWT tokens, verify that they are not expired and have the necessary permissions.
• Check the authentication method (authenticationClass) to ensure it matches the required method for the operation.

Example Error Message:

"errorMessage": "Authentication failed due to invalid JWT token"

3. Permission Denied

Symptoms:

• You receive a 403 Forbidden error indicating that you do not have permission to perform the requested action.

Possible Causes:

• The user does not have sufficient permissions to access the resource or perform the operation.
• The resource or operation is restricted to certain user roles or groups.

Resolution:

• Verify the user's permissions and roles to ensure they have access to the requested resource or operation.
• Check the resource's access control settings to determine if additional permissions are required.
• If necessary, contact your system administrator to adjust permissions or roles.

Example Error Message:

"errorMessage": "You do not have permission to access this resource"

4. Resource Not Found

Symptoms:

• You receive a 404 Not Found error indicating that the specified resource could not be found.

Possible Causes:

• The resource ID or identifier used in the query is incorrect or does not exist.
• The resource has been deleted or moved to a different location.
• The namespace or schema in the __meta__ object is incorrect.

Resolution:

• Verify that the resource ID or identifier is correct and exists in the database.
• Check the namespace and schema in the __meta__ object to ensure they correctly reference the resource.
• If the resource was recently deleted or moved, update your query to reflect the correct location or restore the resource if possible.

Example Error Message:

"errorMessage": "Resource not found for the given ID"

5. Server Errors

Symptoms:

• You receive a 500 Internal Server Error indicating a server-side issue.

Possible Causes:

• An unexpected error occurred on the server, such as a failed database operation or a bug in the backend code.
• The server is overloaded or experiencing temporary issues.

Resolution:

• Retry the operation after a few minutes, as server issues can be temporary.
• If the issue persists, review the server logs or contact your system administrator for further investigation.
• Ensure that your query does not contain any operations or requests that could overload the server (e.g., large data retrievals without pagination).

Example Error Message:

"errorMessage": "An unexpected server error occurred"

6. Handling Validation Errors

Symptoms:

• You receive an error indicating that certain data fields failed validation.

Possible Causes:

• Required fields are missing or contain invalid data.
• The data does not meet the required format, length, or type constraints.

Resolution:

• Review the validation rules for the fields in your query and ensure that all required fields are included and properly formatted.
• Use appropriate data types and formats for each field. For example, ensure that date fields follow the required date format.
• If you receive a specific validation error, correct the data according to the guidance provided in the error message.

Example Error Message:

"errorMessage": "Validation failed: 'email' field must be a valid email address"

7. Performance Issues

Symptoms:

• Queries take too long to execute or return incomplete data.

Possible Causes:

• Large datasets are being retrieved without using pagination.
• Complex queries are not optimized, leading to excessive processing time.
• The server is under heavy load or the database is slow.

Resolution:

• Implement pagination to limit the number of results returned in each query.
• Optimize your queries by reducing unnecessary complexity, such as by limiting the number of nested fields or avoiding costly operations.
• Consider caching frequently accessed data to reduce load on the server.

Example:

"message": "Consider adding pagination to improve query performance"