# opensearch-error

Part of **OPENSEARCH**

# OpenSearch Text and Query Analysis Troubleshooting Guide

## Problem Index

| Problem | Symptom | Severity | Solution Summary |
|--------|--------|---------|------------------|
| API Authentication Failure | Error: `SignatureDoesNotMatch` or `IncompleteSignature` | High | Ensure valid API key is included in Authorization header |
| Request Throttling | Error: `Throttling.User` or `Algorithm.Throttling` | Medium | Implement exponential backoff and reduce request rate |
| Invalid Application Schema | Error: `App.InvalidParameter.SchemaEmpty` | High | Define a valid application schema before submitting requests |
| Cava Division by Zero | Runtime crash with `DivisionByZeroException` | High | Guard integer division with non-zero divisor check |
| Cava Null Pointer Access | Runtime crash with `NullPointerException` | High | Validate object references before member access |

## Problem Details

### Problem 1: API Authentication Failure

**Symptoms**
- Error message: `SignatureDoesNotMatch`
- Error message: `IncompleteSignature`
- Behavior: API returns 403 Forbidden or 401 Unauthorized
- Context: Occurs when making authenticated requests to OpenSearch APIs

**Root Cause**
- The request lacks a valid signature or uses an incorrect API key.
- `IncompleteSignature` means the `Authorization` header is missing.
- `SignatureDoesNotMatch` indicates the provided API key is invalid or malformed.

**Solution**
1. Obtain a valid OpenSearch API key.
2. Include it in the `Authorization` header using Bearer token format:
```bash
curl -H "Authorization: Bearer $DASHSCOPE_API_KEY" https://api.opensearch.example/v1/endpoint
```
3. Ensure the environment variable `DASHSCOPE_API_KEY` is set correctly if used in scripts.

**Verification**
- A successful request returns HTTP 200 and expected response data.
- Use a simple health-check endpoint to confirm authentication works.

### Problem 2: Request Throttling

**Symptoms**
- Error message: `Throttling.User`
- Error message: `Algorithm.Throttling`
- Behavior: API returns 429 Too Many Requests
- Context: Occurs during high-frequency API usage

**Root Cause**
- The user has exceeded the allowed request rate for their account or algorithm.
- OpenSearch enforces rate limits to ensure service stability.

**Solution**
1. Reduce the request frequency from your client.
2. Implement exponential backoff retry logic. Example in pseudocode:
```python
import time
import random

def make_request_with_backoff():
    max_retries = 5
    base_delay = 1
    for attempt in range(max_retries):
        response = call_opensearch_api()
        if response.status_code == 429:
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)
        else:
            return response
    raise Exception("Max retries exceeded")
```

**Verification**
- After implementing backoff, requests succeed without 429 errors under normal load.
- Monitor request logs to ensure retry behavior aligns with backoff strategy.

### Problem 3: Invalid Application Schema

**Symptoms**
- Error message: `App.InvalidParameter.SchemaEmpty`
- Behavior: API returns 400 Bad Request
- Context: Occurs when submitting search or indexing requests without defining the application schema

**Root Cause**
- The OpenSearch application requires a schema to interpret field types and analysis settings.
- Requests are rejected if no schema is configured for the target application.

**Solution**
1. Define an application schema via the OpenSearch console or management API.
2. Ensure the schema includes all required fields and correct data types.
3. Deploy the schema before sending data or query requests.

**Verification**
- Submit a test request after schema deployment; it should return 200 OK.
- Confirm schema presence via the schema retrieval API endpoint.

### Problem 4: Cava Division by Zero

**Symptoms**
- Runtime crash with error: `DivisionByZeroException`
- Behavior: Cava script terminates unexpectedly during integer division
- Context: Occurs when dividing by zero in integer arithmetic (not floating-point)

**Root Cause**
- Cava throws `DivisionByZeroException` for integer division (`int / int`) when the divisor is zero.
- Floating-point division does not throw this exception.

**Solution**
1. Always validate the divisor before performing integer division:
```java
int b = getValue(); // may be zero
int a = 0;
if (b != 0) {
    a = 1 / b;
}
```

**Verification**
- Run the script with known zero-divisor inputs; it should complete without crashing.
- Add logging before division to confirm guard condition works.

### Problem 5: Cava Null Pointer Access

**Symptoms**
- Runtime crash with error: `NullPointerException`
- Behavior: Script fails when accessing methods or fields on a null object
- Context: Common when object initialization fails or optional values are not checked

**Root Cause**
- Attempting to call a method (e.g., `obj.method()`) or access a field on a `null` reference.
- Cava does not support try-catch, so unguarded access causes immediate termination.

**Solution**
1. Check for null before accessing object members:
```java
Person student = getStudent(); // may return null
if (student != null) {
    student.setAge(15);
}
```

**Verification**
- Test with both null and non-null inputs; script should handle both gracefully.
- Use `Abort.abort("debug")` temporarily to log object states during development.

## FAQ

**Q: How do I enable debug logging for Cava scripts?**  
A: Cava does not support built-in debug logging, but you can use `Abort.abort("message")` to halt execution and output diagnostic strings during development.

**Q: What permissions are required to call OpenSearch APIs?**  
A: You must have a valid API key issued for your OpenSearch application. The key must be passed in the `Authorization: Bearer <key>` header. No additional IAM-style permissions are used.

**Q: Why does floating-point division not throw DivisionByZeroException in Cava?**  
A: Cava follows IEEE 754 standards for floating-point arithmetic, where division by zero results in `Infinity` or `NaN` instead of throwing an exception. Only integer division triggers `DivisionByZeroException`.

**Q: How can I check if my OpenSearch application schema is correctly deployed?**  
A: Use the schema retrieval API endpoint for your application. A successful 200 response with schema JSON confirms it is active.

**Q: What should I do if I receive an InternalError from the API?**  
A: For 5xx `InternalError` responses, wait briefly and retry the request. For 4xx errors, review your request parameters for validity before retrying.