actix/actix-web · error · actix_multipart::Error

Unknown field: {_0}

Error message

Unknown field: {_0}

What it means

MultipartError::UnknownField(String) (multipart/error.rs:92-94) is emitted by the derived MultipartCollect implementation (actix-multipart-derive/src/lib.rs:135) when an incoming multipart part's name does not match any declared field of the struct and the struct opts in to denying unknown fields (deny_unknown_fields). It maps to HTTP 400 BadRequest. Without deny_unknown_fields, unknown parts are silently ignored.

Source

Thrown at actix-multipart/src/error.rs:92

    /// Form field handler raised error.
    #[display("An error occurred processing field: {name}")]
    Field {
        name: String,
        source: actix_web::Error,
    },

    /// Duplicate field found (for structure that opted-in to denying duplicate fields).
    #[display("Duplicate field found: {_0}")]
    #[from(ignore)]
    DuplicateField(#[error(not(source))] String),

    /// Required field is missing.
    #[display("Required field is missing: {_0}")]
    #[from(ignore)]
    MissingField(#[error(not(source))] String),

    /// Unknown field (for structure that opted-in to denying unknown fields).
    #[display("Unknown field: {_0}")]
    #[from(ignore)]
    UnknownField(#[error(not(source))] String),
}

/// Return `BadRequest` for `MultipartError`.
impl ResponseError for Error {
    fn status_code(&self) -> StatusCode {
        match &self {
            Error::Field { source, .. } => source.as_response_error().status_code(),
            Error::ContentTypeIncompatible => StatusCode::UNSUPPORTED_MEDIA_TYPE,
            _ => StatusCode::BAD_REQUEST,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

View on GitHub (pinned to 937960ca67)

Solutions

1. Remove the unexpected field from the client request, or fix the name typo.
2. If the extra field is intentional, add it to the struct or remove deny_unknown_fields.
3. Log the offending field name (it is included in the error) to pinpoint the mismatch.

Example fix

// before: unknown field rejected
#[derive(MultipartForm)]
#[multipart(deny_unknown_fields)]
struct Form { name: String }   // client also sends 'age'

// after: accept and capture it
#[derive(MultipartForm)]
#[multipart(deny_unknown_fields)]
struct Form { name: String, age: Option<String> }

// Client-side: filter the FormData to known field names before sending.
const allowed = new Set(['name', 'age']);
for (const key of [...fd.keys()]) {
  if (!allowed.has(key)) fd.delete(key);
}

// 400 UnknownField is returned by the extractor; customise via error handler.
// Downcast the ResponseError to MultipartError::UnknownField(name)
// to show the offending field name to the caller.

When it happens

Trigger: A multipart/form-data request contains a part whose Content-Disposition name is not a field of the target struct, and the struct is annotated with #[multipart(deny_unknown_fields)]. The derive macro's handle_field falls through to the UnknownField branch.

Common situations: Client sends an extra field the backend does not expect, a newer frontend shipping fields the older backend lacks, or a typo in the field name on either side.

Related errors

• Duplicate field found: {_0}
• Required field is missing: {_0}
• Multiple fields named: `{}`
• `MultipartForm` can only be derived for structs
• `MultipartForm` can only be derived for a struct with named

AI-assisted analysis of actix/actix-web@937960ca67 (2026-08-06). Data as JSON: /data/errors/fa3db336645960ac.json. Report an issue: GitHub.