stalwartlabs/stalwart · error · ScimError

The size of the bulk operation exceeds the maxPayloadSize ({

Error message

The size of the bulk operation exceeds the maxPayloadSize ({max_payload_size}).

What it means

A SCIM Error with status 413 built by `Error::max_payload_size_exceeded(max_payload_size)`. It is thrown when a single operation inside a SCIM bulk request exceeds the server's maxPayloadSize limit; the detail reports the configured byte limit.

Source

Thrown at crates/scim-proto/src/message/error.rs:189

        Error::new(404)
    }

    pub fn conflict(detail: impl Into<Cow<'static, str>>) -> Self {
        Error::new(409).with_detail(detail)
    }

    pub fn precondition_failed() -> Self {
        Error::new(412)
    }

    pub fn max_operations_exceeded(max_operations: usize) -> Self {
        Error::new(413).with_detail(format!(
            "The number of operations in the bulk request exceeds the maxOperations ({max_operations})."
        ))
    }

    pub fn max_payload_size_exceeded(max_payload_size: usize) -> Self {
        Error::new(413).with_detail(format!(
            "The size of the bulk operation exceeds the maxPayloadSize ({max_payload_size})."
        ))
    }

    pub fn internal_error() -> Self {
        Error::new(500)
    }

    pub fn not_implemented() -> Self {
        Error::new(501)
    }

    pub fn is_client_error(&self) -> bool {
        (400..500).contains(&self.status)
    }
}

impl Serialize for Error {

View on GitHub (pinned to e962003857)

Solutions

Trim or externalize large attributes (photos, binary data) so each operation fits under maxPayloadSize.
Check /ServiceProviderConfig for bulk.maxPayloadSize and validate operation sizes before sending.
Split the oversized record's data across multiple operations or requests.

Example fix

// before
bulk_ops.push(op_with_huge_photo);
// after
user.photos = None; // or link a URL instead of embedding base64
bulk_ops.push(user.into_op());

Defensive patterns

Strategy: validation

Validate before calling

let max_bytes = cfg.bulk.as_ref().map(|b| b.max_payload_size).unwrap_or(default);
for op in &operations {
    let size = serde_json::to_vec(op)?.len();
    if size > max_bytes { /* shrink: drop photos/binary attrs or split op */ }
}

Prevention

Serialize and size-check each bulk operation before sending.
Avoid embedding base64 photos/large binaries in SCIM records; use URLs.
Store maxPayloadSize per provider in your integration config.

When it happens

Trigger: A bulk operation whose serialized payload (e.g. a user record with large photo/enterprise data) exceeds maxPayloadSize, causing this constructor to run with that limit.

Common situations: Users with huge base64-encoded photos or entitlement lists blow past the per-operation byte cap; a server hardening change lowered maxPayloadSize; migrating providers with different payload caps.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

AI-assisted analysis of stalwartlabs/stalwart@e962003857 (2026-09-06). Data as JSON: /api/errors/588c4a800a93abac. Report an issue: GitHub.