Skip to content

docs: clarify OUT_OF_MEMORY threshold behavior #422

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alangmartini wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: clarify OUT_OF_MEMORY threshold behavior #422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a45b9b1
docs: clarify OUT_OF_MEMORY threshold behavior
alangmartini Jan 15, 2026
64cb7c9
docs: apply OUT_OF_MEMORY clarification to versions 26.0-28.0
alangmartini Jan 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion docs-site/content/26.0/api/cluster-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,9 +442,22 @@ curl "http://localhost:8108/health"
</template>
</Tabs>

When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
set to either `OUT_OF_DISK` or `OUT_OF_MEMORY`.

The `OUT_OF_MEMORY` error is triggered when the `--memory-used-max-percentage` server parameter is set to less than `100`
and free memory falls below the calculated threshold. The threshold is determined as:
`min(500MB, (100 - memory_used_max_percentage)% × total_memory)`.

For example, with `--memory-used-max-percentage=90` on an 8GB system:
- Percentage-based threshold: (100-90)% × 8GB = 800MB free memory required
- Final threshold: min(500MB, 800MB) = 500MB
- Writes are rejected when free memory drops below 500MB

When `--memory-used-max-percentage=100` (default), the resource check is skipped entirely and no memory-based rejection occurs.

If `--memory-used-max-percentage` is below 100 and the threshold is reached, Typesense will reject write operations to prevent system instability.

#### Definition
`GET ${TYPESENSE_HOST}/health`

Expand Down
15 changes: 14 additions & 1 deletion docs-site/content/27.0/api/cluster-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,9 +442,22 @@ curl "http://localhost:8108/health"
</template>
</Tabs>

When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
set to either `OUT_OF_DISK` or `OUT_OF_MEMORY`.

The `OUT_OF_MEMORY` error is triggered when the `--memory-used-max-percentage` server parameter is set to less than `100`
and free memory falls below the calculated threshold. The threshold is determined as:
`min(500MB, (100 - memory_used_max_percentage)% × total_memory)`.

For example, with `--memory-used-max-percentage=90` on an 8GB system:
- Percentage-based threshold: (100-90)% × 8GB = 800MB free memory required
- Final threshold: min(500MB, 800MB) = 500MB
- Writes are rejected when free memory drops below 500MB

When `--memory-used-max-percentage=100` (default), the resource check is skipped entirely and no memory-based rejection occurs.

If `--memory-used-max-percentage` is below 100 and the threshold is reached, Typesense will reject write operations to prevent system instability.

#### Definition
`GET ${TYPESENSE_HOST}/health`

Expand Down
13 changes: 13 additions & 0 deletions docs-site/content/27.1/api/cluster-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -477,6 +477,19 @@ curl "http://localhost:8108/health"
When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
set to either `OUT_OF_DISK` or `OUT_OF_MEMORY`.

The `OUT_OF_MEMORY` error is triggered when the `--memory-used-max-percentage` server parameter is set to less than `100`
and free memory falls below the calculated threshold. The threshold is determined as:
`min(500MB, (100 - memory_used_max_percentage)% × total_memory)`.

For example, with `--memory-used-max-percentage=90` on an 8GB system:
- Percentage-based threshold: (100-90)% × 8GB = 800MB free memory required
- Final threshold: min(500MB, 800MB) = 500MB
- Writes are rejected when free memory drops below 500MB

When `--memory-used-max-percentage=100` (default), the resource check is skipped entirely and no memory-based rejection occurs.

If `--memory-used-max-percentage` is below 100 and the threshold is reached, Typesense will reject write operations to prevent system instability.

#### Definition
`GET ${TYPESENSE_HOST}/health`

Expand Down
13 changes: 13 additions & 0 deletions docs-site/content/28.0/api/cluster-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -477,6 +477,19 @@ curl "http://localhost:8108/health"
When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
set to either `OUT_OF_DISK` or `OUT_OF_MEMORY`.

The `OUT_OF_MEMORY` error is triggered when the `--memory-used-max-percentage` server parameter is set to less than `100`
and free memory falls below the calculated threshold. The threshold is determined as:
`min(500MB, (100 - memory_used_max_percentage)% × total_memory)`.

For example, with `--memory-used-max-percentage=90` on an 8GB system:
- Percentage-based threshold: (100-90)% × 8GB = 800MB free memory required
- Final threshold: min(500MB, 800MB) = 500MB
- Writes are rejected when free memory drops below 500MB

When `--memory-used-max-percentage=100` (default), the resource check is skipped entirely and no memory-based rejection occurs.

If `--memory-used-max-percentage` is below 100 and the threshold is reached, Typesense will reject write operations to prevent system instability.

#### Definition
`GET ${TYPESENSE_HOST}/health`

Expand Down
13 changes: 13 additions & 0 deletions docs-site/content/29.0/api/cluster-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -477,6 +477,19 @@ curl "http://localhost:8108/health"
When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
set to either `OUT_OF_DISK` or `OUT_OF_MEMORY`.

The `OUT_OF_MEMORY` error is triggered when the `--memory-used-max-percentage` server parameter is set to less than `100`
and free memory falls below the calculated threshold. The threshold is determined as:
`min(500MB, (100 - memory_used_max_percentage)% × total_memory)`.

For example, with `--memory-used-max-percentage=90` on an 8GB system:
- Percentage-based threshold: (100-90)% × 8GB = 800MB free memory required
- Final threshold: min(500MB, 800MB) = 500MB
- Writes are rejected when free memory drops below 500MB

When `--memory-used-max-percentage=100` (default), the resource check is skipped entirely and no memory-based rejection occurs.

When this condition is met, Typesense will reject write operations to prevent system instability.
Copy link
Copy Markdown
Member

@jasonbosco jasonbosco Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence looks out of place, when the previous sentence says no rejection occurs.


#### Definition
`GET ${TYPESENSE_HOST}/health`

Expand Down
2 changes: 1 addition & 1 deletion docs-site/content/29.0/api/server-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ Command line arguments can be passed to the server as `--parameter=value`.
| `--cache-num-entries` | false | Number of entries to be stored in the LRU cache used for storing search query responses. Default: `1000`. |
| `--embedding-cache-num-entries` | false | Number of entries to be stored in the LRU cache used for storing text embeddings returned by remote embedders. Default: `100`. |
| `--disk-used-max-percentage` | false | Reject writes when used disk space exceeds this percentage. Default: `100` (never reject). |
| `--memory-used-max-percentage` | false | Reject writes when used memory usage exceeds this percentage. Default: `100` (never reject). |
| `--memory-used-max-percentage` | false | Reject writes when free memory falls below a threshold. The threshold is calculated as the minimum of 500MB or `(100 - this_percentage)% × total_memory`. This will trigger an `OUT_OF_MEMORY` error. Default: `100` (resource check is skipped entirely, no rejection occurs). |
| `--healthy-read-lag` | false | Reads are rejected if the updates lag behind this threshold. Default: `1000`. |
| `--healthy-write-lag` | false | Writes are rejected if the updates lag behind this threshold. Default: `500`. |
| `--snapshot-interval-seconds` | false | Frequency of replication log snapshots. Default: `3600` follower recovery.<br><br>**NOTE**: Frequent snapshotting helps in faster recovery from a cold start. However, if this value is too low for a large dataset, repeated snapshotting can actually slow down follower recovery. |
Expand Down
13 changes: 13 additions & 0 deletions docs-site/content/30.0/api/cluster-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -477,6 +477,19 @@ curl "http://localhost:8108/health"
When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
set to either `OUT_OF_DISK` or `OUT_OF_MEMORY`.

The `OUT_OF_MEMORY` error is triggered when the `--memory-used-max-percentage` server parameter is set to less than `100`
and free memory falls below the calculated threshold. The threshold is determined as:
`min(500MB, (100 - memory_used_max_percentage)% × total_memory)`.

For example, with `--memory-used-max-percentage=90` on an 8GB system:
- Percentage-based threshold: (100-90)% × 8GB = 800MB free memory required
- Final threshold: min(500MB, 800MB) = 500MB
- Writes are rejected when free memory drops below 500MB

When `--memory-used-max-percentage=100` (default), the resource check is skipped entirely and no memory-based rejection occurs.

If `--memory-used-max-percentage` is below 100 and the threshold is reached, Typesense will reject write operations to prevent system instability.

#### Definition
`GET ${TYPESENSE_HOST}/health`

Expand Down
2 changes: 1 addition & 1 deletion docs-site/content/30.0/api/server-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ Command line arguments can be passed to the server as `--parameter=value`.
| `--cache-num-entries` | false | Number of entries to be stored in the LRU cache used for storing search query responses. Default: `1000`. |
| `--embedding-cache-num-entries` | false | Number of entries to be stored in the LRU cache used for storing text embeddings returned by remote embedders. Default: `100`. |
| `--disk-used-max-percentage` | false | Reject writes when used disk space exceeds this percentage. Default: `100` (never reject). |
| `--memory-used-max-percentage` | false | Reject writes when used memory usage exceeds this percentage. Default: `100` (never reject). |
| `--memory-used-max-percentage` | false | Reject writes when free memory falls below a threshold. The threshold is calculated as the minimum of 500MB or `(100 - this_percentage)% × total_memory`. This will trigger an `OUT_OF_MEMORY` error. Default: `100` (resource check is skipped entirely, no rejection occurs). |
| `--healthy-read-lag` | false | Reads are rejected if the updates lag behind this threshold. Default: `1000`. |
| `--healthy-write-lag` | false | Writes are rejected if the updates lag behind this threshold. Default: `500`. |
| `--snapshot-interval-seconds` | false | Frequency of replication log snapshots. Default: `3600` follower recovery.<br><br>**NOTE**: Frequent snapshotting helps in faster recovery from a cold start. However, if this value is too low for a large dataset, repeated snapshotting can actually slow down follower recovery. |
Expand Down