docs: execution errors reference

[marc0olo]

Summary

• Trap errors: trapped, trapped explicitly with cause/fix guidance
• Instruction and memory limit errors: instruction limit, memory access, slice overrun, out of memory, Wasm memory limit, reserved Motoko pages
• Cycles errors: 10 entries covering insufficient cycles, reserved cycles limit, create/install cycle requirements
• System API constraint errors: wrong-mode calls, oversized payloads/certified data, method name/payload limits
• Wasm module validation errors: method not found, module not found, too large, duplicate exports, function/global limits
• Canister lifecycle errors: invalid controller, not found, not empty, delete errors, install rate limits, upgrade option errors
• Subnet capacity errors: compute/memory/custom section oversubscribed, out of IDs, maximum canisters
• Snapshot and metadata errors

Sync recommendation

informed by dfinity/portal — docs/references/execution-errors.mdx; docs/building-apps/canister-management/trapping.mdx; docs/building-apps/canister-management/resource-limits.mdx

[marc0olo]

Review: Execution Errors

Must fix

• Broken GitHub link with wrong path: Line 28 links to https://github.com/dfinity/cdk-rs/blob/main/src/ic-cdk/src/printer.rs. This file does not exist in the current cdk-rs codebase. The repo was restructured: the path src/ic-cdk/src/ no longer exists (the correct root is ic-cdk/src/), and printer.rs itself was removed entirely. The panic hook functionality now lives in ic-cdk-executor/src/machinery.rs as setup_panic_hook, and crucially it is set up automatically by ic-cdk macros (#[update], #[query], etc.) via in_tracking_executor_context — developers do not need to manually install a panic hook. The sentence should be rewritten to reflect that Rust canisters using ic-cdk macros automatically get human-readable panic messages, without linking to a non-existent file. Suggested fix: "Rust canisters using ic-cdk macros automatically convert panics to ic0.trap calls with a human-readable message including the file, line, and panic reason."

• Inaccurate description of canister deletion lifecycle (line 583): The "Delete canister self" section states a canister "will eventually be deleted automatically when its cycle balance drops to zero." This skips the intermediate frozen state. The correct lifecycle is: when the cycle balance drops below the freezing threshold, the canister is frozen (stops executing); only when the balance reaches zero is it deleted. The portal source describes both steps: "if it burns enough cycles, it will eventually be frozen (when the balance drops below its freezing threshold). If the cycles balance then drops to zero, the canister will be deleted." Suggested fix: add "it will first be frozen when its cycle balance falls below the freezing threshold, and eventually deleted when the balance reaches zero."

Suggestions

• Second variant of "Insufficient cycles in memory grow" not covered: The portal source contains two distinct variants of this error. The new page only shows the simple form: "Canister cannot grow memory by 65536 bytes due to insufficient cycles." A second variant exists — "Canister cannot grow memory by 1000000000 bytes due to insufficient cycles. At least 10000000000 additional cycles are required." — which occurs for operations like snapshot, install, and upload_chunk and includes the "At least X additional cycles" suffix. Developers encountering that form of the message may not find it in the reference. Consider adding a note that the error message may include an "At least X additional cycles required" suffix in some cases, or documenting the second form alongside the first.

• Wasm heap memory limit note could mention wasm64: docs/reference/cycles-costs.md documents that the Wasm heap limit is 4 GiB for wasm32 and 6 GiB for wasm64. The "Out of memory" section (line 107) and "Wasm memory limit exceeded" section (line 125) only mention 4 GiB. For completeness, a brief parenthetical like "(4 GiB for wasm32, 6 GiB for wasm64)" could avoid confusion for developers targeting wasm64.

• "Reserved pages for old Motoko" fix instruction could be more precise: The fix instruction says to "upgrade to a newer version of icp-cli." This is correct but could be more specific: the issue is the Motoko compiler version bundled with icp-cli. Adding "Any icp-cli version shipping Motoko 0.6.21 or later eliminates this error" would help developers understand what minimum version to target.

Verified

• All internal links resolve correctly:
  • ./cycles-costs.md exists
  • ./ic-interface-spec.md exists
  • ../guides/canister-management/lifecycle.md resolves to lifecycle.mdx (Astro resolves .md to .mdx)
  • ../guides/canister-management/cycles-management.md resolves to cycles-management.mdx
  • ../guides/canister-management/large-wasm.md exists
  • ../guides/canister-management/optimization.md exists
• All instruction limit values in the table (40B update/heartbeat/timer, 5B query, 300B install/upgrade, 200M inspect_message) match docs/reference/cycles-costs.md
• Response size limits (2 MiB replicated, 3 MiB query) match docs/reference/cycles-costs.md
• Wasm module size limit (100 MiB) matches docs/reference/cycles-costs.md
• Stable memory limit (500 GiB) and Wasm heap limit (4 GiB) match docs/reference/cycles-costs.md
• Same-subnet inter-canister payload limit (10 MiB) matches docs/reference/cycles-costs.md
• All 57 error entries from the portal source are present in the new page (the portal has a duplicate "Insufficient cycles in memory grow" entry that is intentionally consolidated to one)
• No dfx references present
• No internetcomputer.org/docs/ or docs.internetcomputer.org links present
• No mo:base imports present
• icp canister status and icp deploy commands verified against .sources/icp-cli/docs/reference/cli.md
• <\!-- Upstream: --> comment present at end of file
• Frontmatter complete (title, description, sidebar order)
• ## Next steps section present at end of page
• Page uses .md format — appropriate for a pure reference page with no interactive components
• All example error messages verified against portal source — messages match accurately
• External GitHub links for canbench (github.com/dfinity/canbench), ic-wasm (github.com/dfinity/ic-wasm), and wasm-strip (github.com/WebAssembly/wabt) point to correct repositories
• ICP dashboard link (https://dashboard.internetcomputer.org/subnets) is correct
• Structural organization into thematic sections (Trap errors, Instruction/memory limits, Cycles errors, System API constraints, Wasm validation, Canister lifecycle, Subnet capacity, Snapshots, Metadata) is a significant improvement over the portal's flat list
• All example error messages match the portal source exactly

[marc0olo]

<!-- feedback-addressed -->
Feedback addressed — PR #70 docs/reference/execution-errors.md

Changes applied

Must-fix items

1. Broken GitHub link — panic hook (line 28)

• Removed the broken link to https://github.com/dfinity/cdk-rs/blob/main/src/ic-cdk/src/printer.rs (file does not exist; printer.rs was removed in a cdk-rs restructure).
• Verified against .sources/cdk-rs: the panic hook now lives in ic-cdk-executor/src/machinery.rs as setup_panic_hook(), and is set up automatically via in_tracking_executor_context — which is called by ic-cdk macros. Developers do not need to manually install anything.
• Rewrote the sentence to: "Rust canisters using ic-cdk macros automatically convert panics to ic0.trap calls with a human-readable message including the file, line, and panic reason."

2. Inaccurate canister deletion lifecycle (line 583)

• The original text said a canister "will eventually be deleted automatically when its cycle balance drops to zero", skipping the frozen state.
• Verified against .sources/portal/docs/references/execution-errors.mdx: the correct lifecycle is frozen first (when balance drops below freezing threshold), then deleted when balance reaches zero.
• Updated to: "it will first be frozen when its cycle balance falls below the freezing threshold, and eventually deleted when the balance reaches zero."

Suggestions applied

3. Second variant of "Insufficient cycles in memory grow"

• Verified: .sources/portal/docs/references/execution-errors.mdx has a second distinct entry for this error (line 600) with the "At least X additional cycles are required" suffix, covering upload_chunk/snapshot/install operations.
• Added a note to the existing section: "For operations like uploading a Wasm chunk, taking a snapshot, or installing code, the error message may include an 'At least X additional cycles are required' suffix indicating the shortfall."

4. wasm64 memory limit clarification

• Verified: docs/reference/cycles-costs.md documents "4 GiB (wasm32) / 6 GiB (wasm64)" for Wasm heap memory.
• Updated "Out of memory" section to: "Wasm heap, up to 4 GiB for wasm32 or 6 GiB for wasm64"
• Updated "Wasm memory limit exceeded" section to mention "maximum (4 GiB for wasm32, 6 GiB for wasm64)"

5. More specific Motoko version for "Reserved pages for old Motoko"

• Verified: .sources/portal/docs/references/execution-errors.mdx confirms the issue is for Motoko 0.6.20 and older.
• Added to the fix instruction: "Any icp-cli version shipping Motoko 0.6.21 or later eliminates this error."

Items skipped

None — all feedback items were factually correct and verified against source material.

Build verification

The build fails due to a pre-existing unrelated issue in docs/guides/backends/https-outcalls.mdx (missing submodule file in .sources/examples/). This error is present on the branch before any of these changes and is not caused by edits to execution-errors.md. The error was confirmed by testing the build with and without the changes — identical failure in both cases.