{"record":{"id":"7b77ca86ef21a570","repo":"neon-bindings/neon","slug":"context-must-be-a-mut-reference-mod","errorCode":null,"errorMessage":"Context must be a `&mut` reference.","messagePattern":"Context must be a `&mut` reference\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/neon-macros/src/export/function/mod.rs","lineNumber":216,"sourceCode":"        None => return Ok(false),\n    };\n\n    // Extract the reference type\n    let ty = match &*ty.ty {\n        // Tried to use a borrowed Channel\n        syn::Type::Reference(ty) if !opts.context && is_channel_type(&ty.elem) => {\n            return Err(syn::Error::new(\n                ty.elem.span(),\n                \"Expected `&mut Cx` instead of a `Channel` reference.\",\n            ))\n        }\n\n        syn::Type::Reference(ty) => ty,\n\n        // Context needs to be a reference\n        _ if opts.context || is_context_type(&ty.ty) => {\n            return Err(syn::Error::new(\n                ty.ty.span(),\n                \"Context must be a `&mut` reference.\",\n            ))\n        }\n\n        // Hint that `Channel` should be swapped for `&mut Cx`\n        _ if is_channel_type(&ty.ty) => {\n            return Err(syn::Error::new(\n                ty.ty.span(),\n                \"Expected `&mut Cx` instead of `Channel`.\",\n            ))\n        }\n\n        _ => return Ok(false),\n    };\n\n    // Not a forced or inferred context\n    if !opts.context && !is_context_type(&ty.elem) {\n        return Ok(false);","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/neon-bindings/neon/blob/38960e4381d9ad13b551cdf2d261f609167c9bc2/crates/neon-macros/src/export/function/mod.rs#L198-L234","documentation":"Compile-time error from Neon's context check: a parameter in the context position was neither a reference type nor otherwise valid — the type is treated as a context type (either `opts.context` is set or `is_context_type()` matched) but it is not a `&mut` reference. Neon requires the execution context argument to be a mutable reference (`&mut Cx`, `&mut FunctionContext`, etc.).","triggerScenarios":"Declaring a context-like parameter by value or as an immutable binding, e.g. `fn f(cx: FunctionContext)` or `fn f(cx: Cx)`, when the macro expects the context slot to be a reference type.","commonSituations":"Porting signatures from other NAPI/Rust-Node frameworks that take contexts by value, dropping the `&mut` when hand-writing the signature, or misremembering whether `Cx` is passed by reference.","solutions":["Add the missing reference: change `cx: FunctionContext` to `mut cx: &mut FunctionContext` (or `&mut Cx`).","Ensure the parameter is exactly a reference type (`syn::Type::Reference`) with `mut`.","Check that you did not accidentally wrap the context in another type (e.g. `Option<...>`, tuples) which is not a reference."],"exampleFix":"// before\nfn my_fn(cx: FunctionContext) -> JsResult<JsNumber> { ... }\n// after\nfn my_fn(mut cx: FunctionContext) -> JsResult<JsNumber> { ... }\n// (macro-generated signature takes `&mut FunctionContext`; write the fn body accordingly)","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"// Ensure the context parameter is written as a mutable reference type:\nfn valid_context(cx: &mut neon::context::FunctionContext) {}\n// A bare (non-reference) context type like `FunctionContext` will fail this check.","tryCatchPattern":"// Compile-time error; pattern for CI gating:\n// if `cargo check` output contains \"Context must be a `&mut` reference.\"\n// then fix the parameter to `&mut ...` before merging.","preventionTips":["Always write the context parameter as `mut cx: &mut <ContextType>`.","Never pass contexts by value.","Run `cargo check` immediately after signature edits."],"tags":["rust","neon","proc-macro","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"38960e4381d9ad13b551cdf2d261f609167c9bc2","analyzedAt":"2026-09-13T09:05:33.640Z","contentChangedAt":"2026-09-13T09:05:33.640Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}