{"record":{"id":"bcbefd4dc63fcfe5","repo":"apache/cassandra","slug":"invalid-null-map-key-for-column-s","errorCode":null,"errorMessage":"Invalid null map key for column %s","messagePattern":"Invalid null map key for column (.+?)","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/restrictions/SimpleRestriction.java","lineNumber":456,"sourceCode":"                {\n                    // For frozen maps, check if any index on the column can support map entry predicates\n                    // either directly or via filtering. If not, throw an error.\n                    if (column.type.isFrozenCollection())\n                    {\n                        for (Index index : indexRegistry.listIndexes())\n                        {\n                            if (index.dependsOn(column)\n                                && !index.supportsMapElementExpression()\n                                && !index.supportsFilteringOnMapElementExpression())\n                            {\n                                throw invalidRequest(Relation.FROZEN_MAP_ENTRY_PREDICATES_NOT_SUPPORTED, column.name);\n                            }\n                        }\n                    }\n\n                    ByteBuffer key = columnsExpression.element(context);\n                    if (key == null)\n                        throw invalidRequest(\"Invalid null map key for column %s\", column.name.toCQLString());\n                    if (key == ByteBufferUtil.UNSET_BYTE_BUFFER)\n                        throw invalidRequest(\"Invalid unset map key for column %s\", column.name.toCQLString());\n                    List<ByteBuffer> values = bindAndGet(context);\n                    filter.addMapEquality(column, key, operator, values.get(0));\n                }\n                break;\n            default: throw new UnsupportedOperationException();\n        }\n    }\n\n    private static ByteBuffer multiInputOperatorValues(ColumnMetadata column, List<ByteBuffer> values)\n    {\n        return ListType.getInstance(column.type, false).pack(values);\n    }\n\n    @Override\n    public String toString()\n    {","sourceCodeStart":438,"sourceCodeEnd":474,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/restrictions/SimpleRestriction.java#L438-L474","documentation":"Thrown by SimpleRestriction.addToRowFilter when a map-column restriction (e.g. `WHERE m[?] = x` or CONTAINS KEY) resolves its map key element to null. Cassandra rejects null map keys because a null key cannot participate in row filtering or map equality lookups.","triggerScenarios":"Executing a CQL statement with a map key restriction whose bound key variable is bound to null, or an expression (e.g. a function/UDF or JSON value) that evaluates to null for the map element, e.g. `SELECT * FROM t WHERE m[null] = 1` or binding null to the key placeholder of `m[?] = ?`.","commonSituations":"Application code binds a null value into the key position of a map restriction; deserialized/JSON input omits the key so it arrives as null; a UDF or collection-access expression returns null instead of a key.","solutions":["Check the value bound to the map key placeholder and substitute a non-null key before executing.","If the key comes from external input, validate it is non-null and reject the request client-side with a clear message.","If the intent is a key-less containment check, use CONTAINS on values instead of a map-key (CONTAINS KEY) restriction.","Use UNSET awareness in drivers: distinguish unset from null and skip the restriction entirely when the key was not provided."],"exampleFix":"// before\nstmt.bind(Map.of(\"key\", requestedKey)); // requestedKey may be null\n// after\nif (requestedKey == null)\n    throw new IllegalArgumentException(\"map key must be provided\");\nstmt.bind(Map.of(\"key\", requestedKey));","handlingStrategy":"validation","validationCode":"if (mapKey == null) throw new IllegalArgumentException(\"map key must be non-null for WHERE m[key] restriction\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate externally supplied keys before binding.","Distinguish null vs unset in your persistence layer.","Prefer value-based CONTAINS over key-based restrictions when keys are optional."],"tags":["cql","invalid-request","null-key","map-restriction"],"backgroundTag":"null-argument","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}