{"record":{"id":"a677721918bbdf40","repo":"apache/cassandra","slug":"invalid-unset-map-key-for-column-s","errorCode":null,"errorMessage":"Invalid unset map key for column %s","messagePattern":"Invalid unset map key for column (.+?)","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/restrictions/SimpleRestriction.java","lineNumber":458,"sourceCode":"                    // 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    {\n        return operator.buildCQLString(columnsExpression, values);\n    }","sourceCodeStart":440,"sourceCodeEnd":476,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/restrictions/SimpleRestriction.java#L440-L476","documentation":"Thrown by SimpleRestriction.addToRowFilter when the map key of a map-column restriction is the UNSET sentinel byte buffer. Cassandra treats UNSET as 'do not apply this binding', which is meaningless for a map key inside a row filter, so it is rejected.","triggerScenarios":"Executing `WHERE m[?] = ?` where the driver binds the key parameter as unset (e.g. unsetByteBuffer() / omitted named parameter), so columnsExpression.element(context) returns ByteBufferUtil.UNSET_BYTE_BUFFER.","commonSituations":"Drivers using named/unset parameter semantics (Java driver setToUnset) where callers skip a parameter assuming it is ignored; batch templates with optional map-key lookups left unset.","solutions":["Bind a concrete non-null key value to the map key parameter instead of unset.","Rebuild the statement without the map-key restriction when the key is unknown, rather than leaving it unset.","Treat unset as a client-side error: validate all bound key positions are set before executing.","Avoid unset semantics for map keys; only the restriction's value parameter can safely be omitted logic-wise."],"exampleFix":"// before\nboundStatement.setToUnset(i); // key left unset\n// after\nif (key == null) throw new IllegalArgumentException(\"map key required\");\nboundStatement.setByteBuffer(i, key);","handlingStrategy":"validation","validationCode":"if (mapKey == null || isUnset(mapKey)) throw new IllegalArgumentException(\"map key must be bound to a concrete value\");","typeGuard":"boolean isSet(ByteBuffer b) { return b != null && b != ByteBufferUtil.UNSET_BYTE_BUFFER; }","tryCatchPattern":"try { session.execute(stmt); } catch (InvalidRequestException e) { if (e.getMessage().contains(\"unset map key\")) rebuildQueryWithoutMapRestriction(); else throw e; }","preventionTips":["Never use setToUnset for map key parameters.","Build the statement dynamically, omitting the restriction entirely when the key is unknown.","Centralize statement binding so unset handling is uniform."],"tags":["cql","invalid-request","unset-value","map-restriction"],"backgroundTag":"invalid-argument-value","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"}