[unionai-docsy-agent]

What changed in the product

flyteorg/flyte-sdk#1657 shipped in flyte v2.12.0, the earliest tag that contains it. With cache="auto", a ContainerTask or flyte.extras.shell task now gets its cache version from what the container runs. Before 2.12.0, every such task got the same version (sha256("")). Editing the command, the script or the image therefore never invalidated the cache.

Signals 487, 828 and 1239 asked for this: they are #1657 being opened, closed and merged. The owner (Peeter Piegaze, 2026-10-20) scoped the change to caching.md.

Page changes

All changes are in content/user-guide/tasks/task-configuration/caching.md.

• Overview:
  • "By default, caching is disabled" now ends with "except for shell tasks and code sandbox tasks".
  • After the "auto" description, one new sentence: for container, shell and code sandbox tasks, flyte 2.12.0 or later generates the version from what the container runs. It links to the new subsection.
• "disable" section: "This is the default behavior" now ends with "except for shell tasks and code sandbox tasks", the same fix as the Overview.
• Cache policies → new "Container and shell tasks" subsection. It says:
  • With behavior="auto" and flyte 2.12.0 or later, the version hashes the following: the image; the command and arguments (for a shell task, the command holds the rendered script); the data directories; the metadata format; and the file input layout. Changing any of them invalidates the cache.
  • Shell tasks and code sandbox tasks default to cache="auto". Container tasks don't cache unless you set cache.
  • In 2.12.0 through 2.12.2, ContainerTask.override() raises a TypeError, so on those versions set cache when you create the task.
  • A code sandbox's code reaches the container as a content-hashed input file, so editing it invalidates the cache through the inputs.
  • env_vars are not part of the version.
  • An image given as a tag reference ("alpine:latest" or flyte.Image.from_base("alpine:latest")) is versioned by the reference string, so the version stays the same when the tag moves.
  • Before 2.12.0, every container and shell task gets the same version. On those versions an edited shell task keeps returning its old result. To avoid this, upgrade flyte or set cache="disable".

Evidence

• Version: git tag --contains on the main: bump unionai-docs-infra to main (#327) #1657 merge commit returns v2.12.0 as the earliest tag.

• Source at v2.12.0:

  • ContainerBodyPolicy (src/flyte/extras/_container.py) hashes _image_identity(image) with the spec.
  • Its docstring says env_vars are left out and that a mutable tag keeps its version.
  • shell/_runtime.py has cache: str = "auto" in both _Shell and create().
  • ContainerTask inherits cache: CacheRequest = "disable" from TaskTemplate.

• Runs: scratch scripts with uv run --with flyte==<v>. Each task was serialized through get_proto_task(...).metadata (discoverable, discovery_version):

  Case	2.12.0	2.11.4
  ContainerTask, no cache set	False	False
  Shell task, no cache set	True, 5502fc56…	True, e3b0c442…
  Shell task, echo b instead of echo a	76012be5… (different)	e3b0c442…
  Shell task, ubuntu:24.04 instead of alpine:3.20	154d2f5e… (different)	e3b0c442…
  Shell task plus env_vars={"X": "1"}	5502fc56… (same)	e3b0c442…
  Shell task, cache="disable"	False	False
  ContainerTask, "alpine:latest" vs Image.from_base("alpine:latest")	both cdcbbc37…	both e3b0c442…

  • On 2.12.0, ContainerTask(...).override(cache="disable") raises TypeError: ContainerTask.__init__() missing 1 required positional argument: 'command'.
  • A shell task object (_Shell) has no override method (AttributeError).
  • The first draft's run also showed a new version on 2.12.0 when a ContainerTask's command, arguments or output_data_dir changes, and when a built image's pip packages change.

• Not run: I didn't push an image or move a real registry tag. The mutable-tag statement rests on the reference-string result above and on the source: nothing in the policy contacts the registry.

Reviewer findings

• Line 224, sentence too long: taken, using your split. The text now names the symptom (the old result comes back) and then the remedy.
• Line 218, semicolon and the override() warning: taken. I split the sentence and added "Set cache when you create the task, because ContainerTask.override() raises a TypeError in flyte 2.12.0." I reproduced the TypeError. I also checked shell tasks: _Shell has no override() at all, so the same advice covers them. I didn't change the general "task.override level" section, because it describes function tasks.
• Question, flyte.Cache passed to shell.create (typed str): I resolved this by removing that workaround. For pre-2.12.0 versions the page now offers only supported values: upgrade flyte, or set cache="disable". A run shows that a flyte.Cache object does work. But recommending something the annotation doesn't allow isn't worth it, since upgrading fixes the problem.

Notes

• Edits re-applied: the previous draft's edits weren't in this checkout. I re-applied them with these fixes and re-ran the version checks above on 2.12.0 and 2.11.4.
• No new code example: a tested container or shell caching example in unionai-examples would help this subsection.
• Unrelated mode change: the working tree shows content/_static/images/deployment/flyte_wf_timeline.svg changing mode from 755 to 644. It was there before my edit and isn't part of this change.
• No open questions for product owners. The shell.create annotation could be widened to CacheRequest upstream, but none of the listed owners covers flyte-sdk caching, so I haven't addressed that to anyone.

docsy left out changes outside the pages a draft may change: content/_static/images/deployment/flyte_wf_timeline.svg.

Pre-flight review

docsy's reviewer read the first draft before it was opened and made 6 findings. The draft was revised twice in response; its last check still made 4 findings. Its summary of the first draft:

Mostly right, but needs changes before merge. The hash inputs and the 2.12.0 version check out against flyte-sdk. Two gaps remain:

1. Shell tasks are cached by default. flyte.extras.shell.create defaults to cache="auto", while ContainerTask defaults to "disable". The page doesn't say so, and line 19 ("By default, caching is disabled") now reads as true for shell tasks too. On flyte before 2.12.0, that default plus the shared version gives stale results without the user opting in (see comments on lines 19 and 217).
2. The Overview sentence drops the version condition (line 30).

A smaller wording fix is on line 215: the shell script is in the command, not the arguments.

I didn't run the description's flyte==2.12.0 / 2.11.4 serialization table and didn't build the site. The mutable-tag statement rests on reading the source only.

Revised in session (Peeter Piegaze, b86bec0)

Docsy's pre-flight found that code sandbox tasks were left out. Checked and fixed:

• Sandbox tasks cache by default. flyte.sandbox.create() defaults to cache="auto" (since v2.0.2) and builds a ContainerTask. Run on 2.12.0 and 2.13.0: the task is a ContainerTask with cache auto and a ContainerBodyPolicy. The Overview, the "disable" section and the subsection now name sandbox tasks.
• Sandbox code is versioned through its inputs, not the cache version. The code is uploaded as the _script input with hash_method=sha256(script content) (sandbox/_code_sandbox.py). Two sandboxes differing only in code get the same cache version (run on 2.13.0). Because the _script input's hash is its content's SHA-256, an edit still changes the cache key and misses the cache. That last step is read from source, not run against a backend. The subsection says so.
• ContainerTask.override() is fixed in 2.12.3. Run on each release: it raises TypeError on 2.12.0, 2.12.1 and 2.12.2, and works on 2.12.3, 2.12.4, 2.12.5 and 2.13.0. The sentence now names 2.12.0 through 2.12.2.

---

Docsy case 487: https://docsy.apps.demo.hosted.unionai.cloud/cases/487

_{Drafted by Docsy, Union.ai's documentation agent, from the product changes and requests in this case. Review it like any PR; close it if it's not wanted.}

[github-actions]

GHA build & deploy preview

Built by .github/workflows/build-pr.yml and deployed to the docs CF Pages project by .github/workflows/deploy-pr-preview.yml.

Branch alias	https://pr-1773-docsy-case-487.docs-dog.pages.dev
This commit	https://f381ab7f.docs-dog.pages.dev
Commit SHA	b86bec0ff43a4ccd22e1f5c0b91a88a291301f54

Updated automatically on every push.

[unionai-docsy-agent]

Docsy actions: what Docsy did on this PR, and at whose direction. Docsy adds a line for each.

• 2026-11-06 17:19 UTC · pushed b86bec0, an edit: Cover code sandbox tasks (flyte.sandbox.create defaults to cache="auto" and builds a ContainerTask with ContainerBodyPolicy, checked on flyte 2.12.0 and 2.13.0); say sandbox code is versioned through its content-hashed _script input; and scope the ContainerTask.override() TypeError to 2.12.0-2.12.2 (fixed in 2.12.3, checked by running each release). · at the direction of Peeter Piegaze (ppiegaze)
• 2026-11-06 17:19 UTC · changed the description · at the direction of Peeter Piegaze (ppiegaze)