E1712 -- Bundle requires a newer SDK

Severity: ERROR. Class: BundleRequiresNewerSDKError. Fix: upgrade the SDK on every agent in the fleet.

What happened

The hosted policy bundle the SDK pulled from the backend declares metadata.min_sdk_version higher than this SDK's own version. The SDK refused the bundle at load time instead of loading it. Tool calls fall through to the configured default_on_missing (deny by default).

Why it matters

Policy bundles published after PR #601 may include rules that use the per-client / per-project selectors:

- deny: Bash:sudo *
  clients: ["cursor"]
  projects: ["proj-prod"]
  reason: "no sudo on cursor in prod"

Pre-#175 SDKs (controlzero Python < 1.5.8, all Node SDKs before the matching milestone) do not implement the clients: / projects: selectors. They would silently treat the selector as wildcard, so the deny above would fire for every agent on every project, not just cursor on prod. A narrow scoped rule becomes a fleet-wide over-block without any signal in the audit log.

Stamping min_sdk_version on the bundle and refusing it loudly is the fail-loud alternative. The customer hears about the gap at the first tool call, not after their agents start denying every action.

How to fix

Upgrade the SDK on every agent in the fleet. The minimum version is named in the error message (Bundle requires controlzero SDK >= X).

Python

pip install -U controlzero

Node

Configure the Control Zero registry once: add @controlzero:registry=https://npm.controlzero.ai to your .npmrc (or run npm config set @controlzero:registry https://npm.controlzero.ai). It applies to npm install and npx for the whole @controlzero scope.

npm install -g @controlzero/sdk@latest
# or per-project
npm install @controlzero/sdk@latest

After the upgrade restart the agent so the new SDK picks up the bundle. Verify with:

controlzero version

The version printed must be greater than or equal to the version named in the error message.

Why the bundle is published at this floor

A dashboard administrator authored a rule with a clients: or projects: selector. Those rules require post-#175 SDKs to enforce correctly. The dashboard shows an amber banner ("SELECTOR_REQUIRES_MIN_SDK") before the save so the administrator knows the fleet floor will lift.

If you want to roll back the bundle to one that older SDKs can load:

1. Edit the offending rule and remove the clients: / projects: keys. The rule becomes fleet-wide again.
2. Re-publish the policy. The next bundle build will OMIT min_sdk_version because no rule needs it.

This is a downgrade in security posture: every agent now obeys the rule, even ones you tried to scope around. Use only as a temporary unblock while you upgrade SDKs.

Catching this error

Python

from controlzero import Client
from controlzero.errors import BundleRequiresNewerSDKError

try:
    cz = Client(api_key="cz_live_...")
except BundleRequiresNewerSDKError as e:
    print(f"Need controlzero >= {e.required}; have {e.actual}")
    print(f"Run: {e.upgrade_command}")
    raise

Node

import { Client, BundleRequiresNewerSDKError } from '@controlzero/sdk';

try {
  const cz = new Client({ apiKey: 'cz_live_...' });
} catch (e) {
  if (e instanceof BundleRequiresNewerSDKError) {
    console.error(`Need controlzero >= ${e.required}; have ${e.actual}`);
    console.error(`Run: ${e.upgradeCommand}`);
  }
  throw e;
}

Back-compatibility

Bundles minted before PR #602 do not stamp min_sdk_version. Every SDK accepts those bundles unchanged. The gate only activates when the dashboard authors a rule with clients: / projects: and republishes.

See also

• GitHub #602 -- the design and rollout for this gate.
• GitHub #175 -- the multi-client / per-project selectors this gate protects.