{"record":{"id":"30eefc29816e7fbd","repo":"Automattic/mongoose","slug":"bad-within-parameter-json-stringify-val","errorCode":null,"errorMessage":"Bad $within parameter: ${JSON.stringify(val)}","messagePattern":"Bad \\$within parameter: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/cast.js","lineNumber":234,"sourceCode":"                context\n              );\n            }\n            if (val.$minDistance != null) {\n              val.$minDistance = numbertype.castForQuery(\n                null,\n                val.$minDistance,\n                context\n              );\n            }\n\n            if (geo === '$within') {\n              const withinType = value.$center\n                  || value.$centerSphere\n                  || value.$box\n                  || value.$polygon;\n\n              if (!withinType) {\n                throw new Error('Bad $within parameter: ' + JSON.stringify(val));\n              }\n\n              value = withinType;\n            } else if (geo === '$near' &&\n                typeof value.type === 'string' && Array.isArray(value.coordinates)) {\n              // geojson; cast the coordinates\n              value = value.coordinates;\n            } else if ((geo === '$near' || geo === '$nearSphere' || geo === '$geoIntersects') &&\n                value.$geometry && typeof value.$geometry.type === 'string' &&\n                Array.isArray(value.$geometry.coordinates)) {\n              if (value.$maxDistance != null) {\n                value.$maxDistance = numbertype.castForQuery(\n                  null,\n                  value.$maxDistance,\n                  context\n                );\n              }\n              if (value.$minDistance != null) {","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/Automattic/mongoose/blob/49cdab01366679723b487ecb754b38570f783289/lib/cast.js#L216-L252","documentation":"For a legacy $within geospatial query, mongoose requires the operator's value to contain one of four recognized shapes: $center, $centerSphere, $box, or $polygon. If none is present, cast() throws this Error and includes JSON.stringify of the value so the malformed shape is visible.","triggerScenarios":"Model.find({ loc: { $within: { $near: [...] } } }); { loc: { $within: {} } }; { loc: { $within: { center: [[0, 0], 5] } } } -- a shape key missing its $ prefix.","commonSituations":"Porting pre-2.4-era MongoDB code or snippets from other libraries; typos dropping the $ from shape keys; mixing $near/$geometry arguments into $within; migrations off legacy geo code where the server dropped $within support anyway.","solutions":["Use a recognized shape: { loc: { $within: { $center: [[0, 0], 5] } } }","Migrate to $geoWithin -- $within is the legacy operator and modern MongoDB servers do not support it","When constructing shapes programmatically, assert that one of the four $-prefixed keys exists before querying"],"exampleFix":"// before\nModel.find({ loc: { $within: { center: [[0, 0], 5] } } });\n\n// after\nModel.find({ loc: { $geoWithin: { $center: [[0, 0], 5] } } });","handlingStrategy":"validation","validationCode":"const WITHIN_SHAPES = ['$center', '$centerSphere', '$box', '$polygon'];\nfunction hasValidWithinShape(v) {\n  return v != null && typeof v === 'object' &&\n    WITHIN_SHAPES.some(k => Object.prototype.hasOwnProperty.call(v, k));\n}\nconst within = filter.loc && filter.loc.$within;\nif (within && !hasValidWithinShape(within)) {\n  throw new TypeError('Bad $within parameter');\n}","typeGuard":"function isWithinQuery(v) {\n  return v != null && typeof v === 'object' &&\n    ['$center', '$centerSphere', '$box', '$polygon'].some(k => k in v);\n}","tryCatchPattern":null,"preventionTips":["Prefer $geoWithin over $within in all new code","Build geo shapes through helper functions that always set the $-prefixed key","Test geo queries against the same server version you run in production"],"tags":["mongoose","geospatial","legacy","query"],"backgroundTag":"invalid-geo-query","analyzedSha":"49cdab01366679723b487ecb754b38570f783289","analyzedAt":"2026-08-21T22:54:00.882Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}