You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/miscellaneous/memory.md
+87-14Lines changed: 87 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,35 +40,108 @@ On the contrary, `stable` memory doesn't require processing during an upgrade. H
40
40
41
41
### Recommendations
42
42
43
-
There are no strict rules governing the choice of memory type for your use case. Ultimately, the decision lies with you, based on what best suits your project. This is why both the [datastore](../build/datastore/index.md) and [storage](../build/storage/index.md) support both memory types.
43
+
There are no strict rules governing the choice of memory type for your use case. Ultimately, the decision depends on your patterns and strategy. That said, **stable memory is strongly recommended** for the vast majority of data storage scenarios.
44
44
45
-
In practice, `heap` memory can be recommended for small datasets or data that require quick or frequent access, while `stable` memory is preferred for large data or data accessed less often.
45
+
Why? Because:
46
46
47
-
This is why, for example, your dapp's bundle assets (including JS, HTML, images, etc.) are stored within the `heap` memory of satellites.
47
+
- It allows you to offload large or infrequently accessed data from the limited heap space.
48
+
- It avoids serialization overhead during upgrades.
49
+
- It supports much larger data volumes.
48
50
49
-
However, this decision, along with the memory limitations, results in a significant portion of the `heap` memory being allocated. Although `stable` memory is slightly slower and comes at a higher cost, it is well-suited for storing data and ensuring smooth smart contract upgrades. This is particularly important for the operation and lifecycle of a project.
51
+
In contrast, `heap` memory is best reserved for:
50
52
51
-
That's why the default option for creating new collections is set to `stable` for both datastore and storage.
53
+
- Serving your frontend assets (HTML, JS, images, etc.).
54
+
- Small, ephemeral datasets that benefit from fast access and won't push the 1 GB heap limit.
55
+
56
+
This is why both the [datastore](../build/datastore/index.md) and [storage](../build/storage/index.md) support both memory types — but default to `stable`, which is also the **recommended** option.
52
57
53
58
### Default usage
54
59
55
-
As mentioned in the previous chapter, your dapp's bundle and assets (everything you deploy to your satellite using `juno deploy`), are stored in the `heap` memory.
60
+
By default, the memory model aligns with these best practices:
56
61
57
-
In contrast, your users (as of Satellite version 0.0.16) and the [analytics](../build/analytics/index.md) data are saved within `stable` memory.
62
+
- Your dapp's frontend assets — everything deployed using `juno deploy` — are stored in `heap` memory.
63
+
- In contrast, your users (as of Satellite version 0.0.16) and the [analytics](../build/analytics/index.md) data are saved within `stable` memory.
|**Capacity**| Max 1 GB | Max 500 GB (minus heap size) |
70
+
|**Performance**| Fast for read and write operations | Slightly slower |
71
+
|**Cost**| Lower cost | Higher cost (~20x) |
72
+
|**Upgrades**| Data must be deserialized/serialized during upgrades | Data are not processed during upgrades |
73
+
|**Usage**| Suitable for small or frequently accessed data | Suitable for large or less frequently accessed data |
74
+
|**Recommendation**| Use sparingly to avoid upgrade friction and size limits | Default and recommended for most use cases |
75
+
76
+
---
77
+
78
+
## Behavior
79
+
80
+
When discussing memory, it's important to understand how WebAssembly (WASM) memory behaves at a lower level.
81
+
82
+
### Memory Growth and Reuse
83
+
84
+
WASM memory can **grow**, but it **cannot shrink**. This behavior is **not specific to Juno** — it's part of the WASM standard and applies across all platforms using WASM.
85
+
86
+
- Once the memory size increases (e.g. due to allocations or data structure growth), the total allocated memory **remains fixed at the new size**, even if you later free or remove data.
87
+
- However, memory that is no longer in use is **internally reused or reallocated**, so your container is not constantly allocating more memory unless needed.
88
+
89
+
### What to Expect
90
+
91
+
- It's normal to see your module's reported memory usage increase over time and **not decrease**, even after deletions or optimizations.
92
+
- The **only time this memory resets** is during an **upgrade**, which reinitializes the heap with the new WASM binary and runtime state.
93
+
- As a result, a growing memory footprint isn't necessarily a problem — but it's worth monitoring, particularly when it comes to the heap, which should not exceed the 1 GB limit.
94
+
95
+
### Best Practices
96
+
97
+
- As recommended in this documentation, **use stable memory** for large or infrequently accessed data to reduce heap pressure and avoid excessive memory growth. In other words, try to avoid using heap memory for anything beyond serving your frontend app.
98
+
-**Keep your heap size well below the 1 GB limit**, especially if you expect frequent upgrades or manage large in-memory state.
99
+
-**Ensure reproducible builds** of your frontend application. On deploy, only actual changes should be pushed to avoid unintentionally bloating memory usage. [Why this matters.](#ensure-your-frontend-build-is-reproducible)
100
+
- Use the Console UI's available tools and metrics to track memory usage and growth patterns over time.
101
+
102
+
---
103
+
104
+
## Exceeding the Heap Memory Limit
105
+
106
+
Every Satellite, and generally any module on Juno, starts with a default heap memory limit of 1 GB. While you can increase this limit in the settings, it's not recommended to go beyond it, as it may cause issues when upgrading your module.
107
+
108
+
The heap includes a bit of metadata, any collections you've created in Datastore and Storage (where using stable memory is advised), and the assets of your frontend application.
109
+
110
+
If you're deploying a really large application (>1 GB) or frequently pushing updates to an application that isn’t reproducible, your heap memory usage can grow unexpectedly and eventually hit the limit.
111
+
112
+
When that happens, your next deployment or update might fail to prevent exceeding the limit, which could lead to issues with your module.
113
+
114
+
```
115
+
Request ID: d7be9..bfcb8
116
+
Reject code: 5
117
+
Reject text: Error from Canister aaaaa-bbbbb-ccccc-ddddd-cai: Canister exceeded its current Wasm memory limit of 1073741824 bytes. The peak Wasm memory usage was 1073872896 bytes. If the canister reaches 4GiB, then it may stop functioning and may become unrecoverable. Please reach out to the canister owner to investigate the reason for the increased memory usage. It might be necessary to move data from the Wasm memory to the stable memory. If such high Wasm memory usage is expected and safe, then the developer can increase the Wasm memory limit in the canister settings..
118
+
Try checking the canister for a possible memory leak or modifying it to use more stable memory instead of Wasm memory. See documentation: https://internetcomputer.org/docs/current/references/execution-errors#wasm-memory-limit-exceeded
119
+
```
120
+
121
+
### Preventing Heap Memory Issues
122
+
123
+
To avoid running into memory limits, it's important to monitor memory usage and follow two key best practices:
124
+
125
+
#### Ensure Your Frontend Build is Reproducible
126
+
127
+
When building your frontend (e.g. with `npm run build`), the output should be identical to the previous build if no changes were made.
128
+
129
+
Why does this help? When you deploy your application, Juno does not clear existing files—it only adds new ones. To optimize this process, Juno compares the names and content (hash values) of all files with those already uploaded. If a file hasn't changed, it is skipped, reducing unnecessary memory usage and saving cycles.
130
+
131
+
If your build output isn’t reproducible, every deployment could introduce slightly different files, even if nothing has changed in your code. Over time, this would lead to unnecessary file accumulation, increasing heap memory usage and eventually causing issues.
132
+
133
+
#### Resolving Heap Memory Issues
134
+
135
+
There are different ways to resolve this issue, and the best approach depends on the features you're using. If you're using Datastore and Storage, we need to find a solution that prevents data loss. If you're only hosting a website, the steps to fix the issue will be much simpler.
136
+
137
+
In any case, the best course of action is to reach out so we can assess your situation and find a tailored solution together.
138
+
139
+
---
68
140
69
141
## Resources
70
142
71
143
-[Measure different collection libraries written in Rust](https://dfinity.github.io/canister-profiling/collections/)
144
+
-[Question about freeing/shrinking memory in WebAssembly design](https://github.com/WebAssembly/design/issues/1300)
Copy file name to clipboardExpand all lines: docs/troubleshooting.md
+2-37Lines changed: 2 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -85,43 +85,8 @@ Note: `vite` may cache the configuration — if the error persists after updatin
85
85
86
86
---
87
87
88
-
### Canister exceeded its current Wasm memory limit
88
+
### My Heap Memory Keeps Growing — Is That Expected?
89
89
90
-
Every Satellite, and generally any module on Juno, starts with a default heap memory limit of 1 GB. While you can increase this limit in the settings, it's not recommended to go beyond it, as it may cause issues when upgrading your module.
91
-
92
-
The heap includes a bit of metadata, any collections you've created in Datastore and Storage (where using stable memory is advised), and the assets of your frontend application.
93
-
94
-
If you're deploying a really large application (>1 GB) or frequently pushing updates to an application that isn’t reproducible, your heap memory usage can grow unexpectedly and eventually hit the limit.
95
-
96
-
When that happens, your next deployment or update might fail to prevent exceeding the limit, which could lead to issues with your module.
97
-
98
-
```
99
-
Request ID: d7be9..bfcb8
100
-
Reject code: 5
101
-
Reject text: Error from Canister aaaaa-bbbbb-ccccc-ddddd-cai: Canister exceeded its current Wasm memory limit of 1073741824 bytes. The peak Wasm memory usage was 1073872896 bytes. If the canister reaches 4GiB, then it may stop functioning and may become unrecoverable. Please reach out to the canister owner to investigate the reason for the increased memory usage. It might be necessary to move data from the Wasm memory to the stable memory. If such high Wasm memory usage is expected and safe, then the developer can increase the Wasm memory limit in the canister settings..
102
-
Try checking the canister for a possible memory leak or modifying it to use more stable memory instead of Wasm memory. See documentation: https://internetcomputer.org/docs/current/references/execution-errors#wasm-memory-limit-exceeded
103
-
```
104
-
105
-
#### Preventing Heap Memory Issues
106
-
107
-
To avoid running into memory limits, it's important to monitor memory usage and follow two key best practices:
108
-
109
-
##### Use Stable Memory for Datastore and Storage
110
-
111
-
Stable memory is designed for long-term storage and helps prevent heap memory from growing uncontrollably. Whenever possible, store large datasets in stable memory instead of the heap.
112
-
113
-
##### Ensure Your Frontend Build is Reproducible
114
-
115
-
When building your frontend (e.g. with `npm run build`), the output should be identical to the previous build if no changes were made.
116
-
117
-
Why does this help? When you deploy your application, Juno does not clear existing files—it only adds new ones. To optimize this process, Juno compares the names and content (hash values) of all files with those already uploaded. If a file hasn't changed, it is skipped, reducing unnecessary memory usage and saving cycles.
118
-
119
-
If your build output isn’t reproducible, every deployment could introduce slightly different files, even if nothing has changed in your code. Over time, this would lead to unnecessary file accumulation, increasing heap memory usage and eventually causing issues.
120
-
121
-
##### Resolving Heap Memory Issues
122
-
123
-
There are different ways to resolve this issue, and the best approach depends on the features you're using. If you're using Datastore and Storage, we need to find a solution that prevents data loss. If you're only hosting a website, the steps to fix the issue will be much simpler.
124
-
125
-
In any case, the best course of action is to reach out so we can assess your situation and find a tailored solution together.
90
+
If your heap memory usage keeps increasing and doesn't go down, even after deleting data — [this is expected behavior](./miscellaneous/memory.md#behavior). See the documentation for why this happens and how to manage it effectively.
0 commit comments