actix/actix-web · warning · Error

Unknown field "{_0}"

Error message

Unknown field "{_0}"

What it means

This is `actix_multipart::form::Error::UnknownField(String)` raised by actix-multipart's typed form deserialization when the struct has opted in to denying unknown fields. It means the multipart body contained a part whose field name does not correspond to any field of the target `MultipartForm` struct. The library rejects the request instead of ignoring the extra part.

Source

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

    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),
}

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 err_report::Report;

    use super::*;

View on GitHub (pinned to c215607f4b)

Solutions

1. Add a matching field to the MultipartForm struct (or fix the rename attribute) so the extra part is recognized.
2. Fix the client form to remove or rename the extra input so it matches the server schema.
3. If extra parts should be tolerated, configure the form to ignore unknown fields instead of denying them.
4. Use the field name in the error to diff the client's multipart payload against the server struct definition.

Example fix

// before: client sends 'comment', struct lacks it
struct Form { file: File }
// after
struct Form { file: File, comment: Option<String> }

// client-side: keep payload keys in sync with the server schema
const ALLOWED = new Set(["file", "comment"]);
const extra = [...formData.keys()].filter((n) => !ALLOWED.has(n));
if (extra.length) throw new Error(`unknown multipart fields: ${extra.join(", ")}`);

// server-side: any field you wish to ignore must exist in the struct; there is no wildcard
derive(MultipartForm)
struct Form { file: File, #[multipart(rename = "comment")] comment: Option<String> }

match form_result {
    Err(e) if e.to_string().contains("Unknown field") =>
        ErrHttpResponse::build(StatusCode::BAD_REQUEST).body("form contains unrecognized field"),
    other => other,
}

When it happens

Trigger: During `MultipartForm::from_request`, a part's name matches no field of the derive(MultipartForm) struct (with deny-unknown-fields behavior active), so parsing fails with the offending name.

Common situations: Client form updated with new inputs while the server struct was not, typos in the input `name` attribute, generic client tooling sending extra metadata fields, or version skew between an older cached frontend and a newer backend.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Duplicate field found "{_0}"
• Required field is missing "{_0}"
• `MultipartForm` can only be derived for a struct with named
• Could not parse size limit `{}`: {}
• Multiple fields named: `{}`

AI-assisted analysis of actix/actix-web@c215607f4b (2026-09-09). Data as JSON: /api/errors/1efa3309e405a505. Report an issue: GitHub.