Skip to content

docs: align invalid controller errors with the replica - #428

Merged
mraszyk merged 8 commits into
mainfrom
docs/execution-errors-invalid-controller
Nov 6, 2026
Merged

mraszyk merged 8 commits into
mainfrom
docs/execution-errors-invalid-controller

Conversation

@mraszyk

@mraszyk mraszyk commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Updates the execution-error reference to explain controller and subnet admin permissions, and aligns the list_canisters reference and interface specification with replicated inter-canister support.

  • Clarifies which canister's controllers are required for code installation and snapshot loading, including when the chunk store is also the target canister.
  • Adds the missing subnet admin error sections, including permissions, supported call types, the errors returned on subnets without subnet admins, and how to resolve the errors; removes the obsolete snapshot-controller error entry.
  • Documents replicated list_canisters calls by subnet admin canisters in the interface-spec prose, formal model, management canister reference, and changelog entry 0.64.1 (2026-07-20).
  • Updates the formal model and caller summary for supported call types, and clarifies that the single-replica warning applies only to query responses.

Verified against dfinity/ic commit 869aa00a6e15ae99de6105cabf8282127d1d017c. Replicated list_canisters support was introduced by dfinity/ic#10643 and included in the July 9 release. Its recorded subnet deployment proposals completed on July 20, which is the date used in the changelog.

Validation

  • npm run build
  • Documentation validation for the changed pages

Document the three roles reported by CanisterInvalidController
(dfinity/ic#11842), add the invalid-controller-subnet-admin section the
replica's error help links to, and remove the CanisterSnapshotNotController
error, which no longer exists.
Subnet admins are only taken into account on rented subnets and cloud
engines on the free cost schedule, and on cloud engines they can access
canisters in every way except rename_canister. Add the
invalid-subnet-admin section the replica's error help links to.
@mraszyk

mraszyk commented Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

Feedback addressed:

  • Documented direct non-replicated queries for list_canisters, while retaining the ingress-update restriction.
  • Added canister_status to rented-subnet admin permissions and clarified that admins bypass status visibility.
  • Scoped the Invalid controller fallback to controller-only operations and distinguished visibility-controlled reads.
  • Updated the PR description to match the implementation and record the verified dfinity/ic commit.

Validation: page validator, git diff --check, and npm run build passed.

@mraszyk
mraszyk marked this pull request as ready for review October 26, 2026 11:08
@mraszyk
mraszyk requested review from a team as code owners October 26, 2026 11:08
Comment thread docs/references/execution-errors.md Resolved
Comment thread docs/references/execution-errors.md Resolved
Comment thread docs/references/execution-errors.md Resolved
…te_canister case

- list_canisters is callable by subnet admin canisters via replicated
  calls (dfinity/ic#10643, on all subnets since 2026-07-20): update the
  interface spec prose, formal model, changelog (0.64.1), the management
  canister reference, and the execution-error page.
- create_canister from a canister on a remote non-NNS subnet is rejected
  by the sender-subnet check before the subnet admin check.
- Cloud engines are always on the free cost schedule.
@mraszyk
mraszyk requested a review from a team as a code owner November 6, 2026 21:31
@github-actions github-actions Bot added the interface-spec Changes to the IC interface specification label Nov 6, 2026
@mraszyk

mraszyk commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Feedback addressed:

  • Removed the unreachable create_canister case for canisters on remote non-NNS subnets; only the ingress case remains.
  • Documented list_canisters as callable by subnet admin canisters via replicated calls (feat: management canister's endpoint list_canisters as inter-canister call ic#10643, rolled out to all subnets on 2026-07-20): interface spec prose, formal model, changelog 0.64.1, and the management canister reference.
  • Dropped the redundant "on the free cost schedule" qualifier for cloud engines.

@mraszyk

mraszyk commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Feedback addressed:

  • Clarified that the chunk-store controller error can refer to the target canister itself, including when store_canister is omitted.
  • Scoped the list_canisters single-replica warning to query responses.
  • Added empty Candid argument validation and the Reply constructor to the formal list_canisters success rule.
  • Updated the PR description to reflect the fixes and distinguish recorded deployment-proposal completion from confirmation that every subnet was running the release.

Validation: all five PR pages passed the documentation validator; git diff --check and npm run build passed using a temporary Node.js v22.23.4 installation.

@mraszyk

mraszyk commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

@pierugo-dfinity Thanks a lot for your detailed review and findings! I've address them, iterated a bit more with Fable and Astra and merging this PR now.

@mraszyk
mraszyk merged commit 755fcfb into main Nov 6, 2026
11 checks passed
@mraszyk
mraszyk deleted the docs/execution-errors-invalid-controller branch November 6, 2026 22:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

interface-spec Changes to the IC interface specification

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants