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 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

What it means

The MemoryLimitExceeded variant of LicenseError (formatted with humansize binary units): the license key is valid, but the cluster's cached total memory exceeds the limit allowed by the license, so license-gated features are unavailable. Like CpuLimitExceeded it is raised from license.check_cluster_resource() when the license is checked against the cached ClusterResource.

Source

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

            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>,
    cached_cluster_resource: ClusterResource,
}

/// The singleton license manager.
pub struct LicenseManager {
    inner: RwLock<Inner>,
}

View on GitHub (pinned to 6469eb736d)

Solutions

1. Reduce total cluster memory (remove nodes or lower per-node memory limits) to fit the license limit.
2. Obtain a license key with a higher memory limit and set it via the `license_key` system parameter.
3. Check the error message's humanized values (actual vs limit) to see exactly how much memory must be removed.

Example fix

// before: raise pod memory beyond license limit
resources: { limits: { memory: '32Gi' } }  # 4 pods x 32Gi = 128Gi > licensed 64Gi
// after: keep total memory within the license
resources: { limits: { memory: '16Gi' } }  # 4 pods x 16Gi = 64Gi <= licensed 64Gi

// Before adding nodes/memory, validate against the license's memory limit
let license = LicenseManager::get().license()?;
let mem_limit = license.rw_credits.limit.memory();
if planned_total_memory_bytes > mem_limit {
    eprintln!("planned memory {} exceeds licensed {}", planned_total_memory_bytes, mem_limit);
}

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

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

When it happens

Trigger: LicenseManager::license() / Feature::check_available while update_cluster_resource() reports total_memory_bytes greater than the license's memory limit — e.g. after adding nodes or raising per-node memory (K8s memory limits, host RAM upgrades).

Common situations: Scaling up cluster memory beyond the licensed quota; Kubernetes memory-limit increases; adding a memory-heavy node; trial/4-core licenses used on large clusters.

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

• a valid license key is set, but it is currently not effectiv
• Not enough memory to run this query, batch memory limit is {
• total_memory_bytes {} is larger than the total memory availa
• The total memory size ({}) is too small. It must be at least
• reserved memory ({}) >= total memory ({}).

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