Skip to content

feat(idl): add org limit and entitlement error details - #8425

Merged
katrogan merged 1 commit into
mainfrom
katrina/org-limit-error-details
Nov 18, 2026
Merged

katrogan merged 1 commit into
mainfrom
katrina/org-limit-error-details

Conversation

@katrogan

Copy link
Copy Markdown
Contributor

Why are the changes needed?

When a server refuses a request because the org is at one of its limits, or isn't entitled to a capability, it can attach a structured error detail saying which limit and by how much. Today those details are defined outside flyteidl2, so the open-source SDK has no generated classes for them and can't show users a readable message. Defining them here lets the SDK and CLI decode them with generated code.

What changes were proposed in this pull request?

New flyteidl2/org/limits.proto (package flyteidl2.org) with two error-detail messages, plus their generated Go, Python, Rust and TypeScript code:

  • OrgLimitExceeded: limit (name), ceiling (the org's value), current (usage), requested, optional tier_default, upgrade_url, and tier, the display name of the tier tier_default belongs to (e.g. "Teams"). tier is a string rather than an enum so a deployment can name its own tiers without an IDL change.
  • OrgEntitlementRequired: entitlement (name), values (for a valued entitlement, the ones the request needed), upgrade_url.

No services or existing messages change.

How was this patch tested?

Labels

  • added

🤖 Generated with Claude Code

OrgLimitExceeded and OrgEntitlementRequired are attached to a refusal when a
request would push an org past one of its limits, or the org isn't entitled
to a capability. Defining them in flyteidl2 lets the SDK and CLI decode them
with generated code and show users which limit was hit, the org's value and
usage, its tier default and where to ask for more.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Katrina Rogan <katroganGH@gmail.com>
@katrogan katrogan added the added Merged changes that add new functionality label Nov 18, 2026
katrogan added a commit to flyteorg/flyte-sdk that referenced this pull request Nov 18, 2026
…ages

The refusal details are now public flyteidl2.org.OrgLimitExceeded and
OrgEntitlementRequired, so the SDK decodes them with the generated classes
instead of descriptors of its own. A detail that only names the older
cloudidl.common.OrgLimitExceeded type is still a refusal, reported with the
server's message, and the Rust controller recognises both names.

- OrgLimit.tier names the tier tier_default belongs to: "The Teams tier
  default is 2."
- An enqueue refused for a missing entitlement fails the child once as a user
  error, like an org limit, instead of retrying and failing as a system error.
- Messages say "Contact sales" to raise a limit or enable an entitlement.
- The CLI error test strips color, which CI forces on.

Needs a flyteidl2 release that includes flyteidl2/org/limits.proto
(flyteorg/flyte#8425).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Katrina Rogan <katroganGH@gmail.com>
@katrogan
katrogan merged commit 2252ea7 into main Nov 18, 2026
25 of 28 checks passed
@katrogan
katrogan deleted the katrina/org-limit-error-details branch November 18, 2026 08:35
katrogan added a commit to flyteorg/flyte-sdk that referenced this pull request Nov 18, 2026
2.0.56 adds flyteidl2/org/limits.proto (flyteorg/flyte#8425), which the org
limit and entitlement decoding imports. The plugin lock files are re-locked
with uv 0.13.4, as CI checks them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Katrina Rogan <katroganGH@gmail.com>
katrogan added a commit to flyteorg/flyte-sdk that referenced this pull request Nov 18, 2026
)

## Why
When Union refuses a request because the org is at one of its limits, or
isn't entitled to a capability, the SDK and CLI show the raw status
("RPC error invoking command…", "Permission denied…"). The server
attaches a structured detail naming the limit; this decodes it.

## What
- Decodes `flyteidl2.org.OrgLimitExceeded` and `OrgEntitlementRequired`
(flyteorg/flyte#8425) with the generated `flyteidl2` classes.
- A refusal that only carries the older
`cloudidl.common.OrgLimitExceeded` (servers from before the public
detail) is still recognised by type name and reported with the server's
message, as today. The Rust controller recognises both names.
- `OrgLimitExceededError` and `ResourceExhaustedError` carry `org_limit`
(`flyte.errors.OrgLimit`: `limit`, `ceiling`, `current`, `requested`,
`tier_default`, `upgrade_url`, `tier`). New
`OrgEntitlementRequiredError` (`entitlement`, `values`, `upgrade_url`).
`max_concurrent_runs` stays a `ResourceExhaustedError`, so the
controller still retries it.
- An enqueue refused for a missing entitlement fails the child once as a
user error the parent can catch, like an org limit, instead of retrying
and failing as a system error.
- Readable messages, e.g.:
- `Org limit max_clusters (4) reached: 4 in use, 1 more requested. The
Teams tier default is 2. Contact sales to raise it:
https://www.union.ai/get-a-quote`
- `Org limit max_concurrent_runs (1000) reached: 1000 in use, 1 more
requested. Wait for running work to finish, or contact sales to raise
it: …`
- `This org isn't entitled to allowed_clouds (coreweave). Contact sales
to enable it: …`
- The CLI's shared error handler prints them for every command, plugin
commands included.

A refusal without a detail keeps today's message. Servers that don't
send `tier_default`, `tier` or `upgrade_url` get the same message
without those parts.

Bumps `flyteidl2` to 2.0.56, which adds `flyteidl2/org/limits.proto`
(flyteorg/flyte#8425), in `pyproject.toml`,
`rs_controller/pyproject.toml` and `rs_controller/Cargo.toml`, with the
root, plugin and `Cargo.lock` lock files.

## Testing
- `tests/internal/controllers/test_org_limits.py`: decoding every field,
a tier default without a tier name, unset vs 0 tier default, the older
detail alone and alongside the public one, unreadable detail falls back,
pickling, type names match the generated messages.
- `tests/internal/controllers/test_org_limit_exceeded.py`: an org limit
or entitlement refusal on enqueue fails the child once, as a user error.
- `tests/flyte/test_run_create_errors.py`: `create_run` at
`max_concurrent_runs` and on an entitlement refusal; `PERMISSION_DENIED`
without the detail unchanged.
- `tests/flyte/cli/test_common_errors.py`: CLI output for each, with
color forced on as in CI.
- `rs_controller`: `cargo test` for both detail names.
- Full unit suite on flyteidl2 2.0.56, and the affected tests on
connectrpc 0.11. ruff, mypy, ty clean.
- Earlier, against a Union staging deployment sending the detail fields,
with an org's `max_secrets` lowered to 1: `flyte create secret` printed
the readable `max_secrets` message with the upgrade link. Not exercised
against a live server: `max_concurrent_runs` (the server usually queues
a run past the cap rather than refusing it) and entitlement refusals (no
server check sends one yet); unit tests cover both.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: Katrina Rogan <katroganGH@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

added Merged changes that add new functionality flyte2

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants