risingwavelabs/risingwave · error · LicenseError

a valid license key is set, but it is currently not effectiv

Error message

a valid license key is set, but it is currently not effective because the CPU core in the cluster ({actual}) exceeds the maximum allowed by the license key ({limit}); consider removing some nodes or acquiring a new license key with a higher limit

What it means

LicenseError::CpuLimitExceeded means the license key itself is valid, but its CPU-core quota is not currently effective: the cluster's cached total CPU cores (actual) exceed the max cores allowed by the license (limit). It is raised by license.check_cluster_resource() when LicenseManager::license() validates the cached ClusterResource, and Feature::check_available surfaces it.

Source

Thrown at src/license/src/manager.rs:205

    /// Used when `license_key` is unset or invalid.
    fn default() -> Self {
        Self {
            sub: "default".to_owned(),
            tier: Tier::Free,
            iss: Issuer::Prod,
            rwu_limit: None,
            exp: u64::MAX,
        }
    }
}

/// The error type for invalid license key when verifying as JWT.
#[derive(Debug, Clone, Error)]
pub enum LicenseError {
    #[error("invalid license key")]
    InvalidKey(#[source] jsonwebtoken::errors::Error),

    #[error(
        "a valid license key is set, but it is currently not effective because the CPU core in the cluster \
        ({actual}) exceeds the maximum allowed by the license key ({limit}); \
        consider removing some nodes or acquiring a new license key with a higher limit"
    )]
    CpuLimitExceeded { limit: u64, actual: u64 },

    #[error(
        "a valid license key is set, but it is currently not effective because the memory in the cluster \
        ({actual}) exceeds the maximum allowed by the license key ({limit}); \
        consider removing some nodes or acquiring a new license key with a higher limit",
        actual = humansize::format_size(*actual, humansize::BINARY),
        limit = humansize::format_size(*limit, humansize::BINARY),
    )]
    MemoryLimitExceeded { limit: u64, actual: u64 },
}

struct Inner {
    license: Result<License, LicenseError>,

View on GitHub (pinned to 6469eb736d)

Solutions

  1. Reduce the number of nodes or per-node CPU cores so total cluster cores are at or below the license limit.
  2. Purchase or renew a license key with a higher CPU-core limit and set it via the `license_key` system parameter.
  3. Scale the cluster back down (remove nodes / shrink CPU requests in Kubernetes) to restore compliance.

Example fix

// before: scale compute to 8 cores total with a 4-core license
kubectl scale deploy/risingwave-compute --replicas=4  # 4 pods x 2 cores = 8 > limit 4
// after: stay within the 4-core license or upgrade it
kubectl scale deploy/risingwave-compute --replicas=2  # 2 pods x 2 cores = 4 <= limit 4
Defensive patterns

Strategy: validation

Validate before calling

// Before scaling, check the licensed core limit against planned cluster size
let license = LicenseManager::get().license()?;
let limit = license.rw_credits.limit.cpu_core();
if planned_total_cores > limit {
    eprintln!("refusing scale-up: {} cores would exceed license limit {}", planned_total_cores, limit);
}

Type guard

fn cpu_limit_error(e: &LicenseError) -> Option<(u64, u64)> {
    match e { LicenseError::CpuLimitExceeded { limit, actual } => Some((*limit, *actual)), _ => None }
}

Try / catch

match LicenseManager::get().license() {
    Ok(license) => enable_feature(license),
    Err(LicenseError::CpuLimitExceeded { limit, actual }) => {
        tracing::warn!(limit, actual, "CPU limit exceeded; feature gated");
        degrade_gracefully();
    }
    Err(e) => return Err(e.into()),
}

Prevention

When it happens

Trigger: LicenseManager::license() (typically via Feature::check_available for a gated feature) while update_cluster_resource() has reported a total_cpu_cores greater than the license's core limit — e.g. after scaling up the cluster or adding nodes with more cores.

Common situations: Auto-scaling or adding compute nodes pushes total cores past the licensed limit; moving from a 4-core trial license to a bigger cluster without upgrading the license; increasing per-node core allocation (e.g. K8s CPU limits) without changing the license.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/7cf88f45d861c833. Report an issue: GitHub.