{"record":{"id":"99c4ca6cb38bbd48","repo":"boto/boto3","slug":"expecting-a-conditionbase-object-got-value-of-t","errorCode":null,"errorMessage":"Expecting a ConditionBase object. Got {value} of type {type(value)}. Use AttributeBase object methods (i.e. Attr().eq()). to generate ConditionBase instances.","messagePattern":"Expecting a ConditionBase object\\. Got (.+?) of type (.+?)\\. Use AttributeBase object methods \\(i\\.e\\. Attr\\(\\)\\.eq\\(\\)\\)\\. to generate ConditionBase instances\\.","errorType":"exception","errorClass":"DynamoDBNeedsConditionError","httpStatus":null,"severity":"error","filePath":"boto3/dynamodb/conditions.py","lineNumber":344,"sourceCode":"\n        :type condition: ConditionBase\n        :param condition: A condition to be built into a condition expression\n            string with any necessary placeholders.\n\n        :type is_key_condition: Boolean\n        :param is_key_condition: True if the expression is for a\n            KeyConditionExpression. False otherwise.\n\n        :rtype: (string, dict, dict)\n        :returns: Will return a string representing the condition with\n            placeholders inserted where necessary, a dictionary of\n            placeholders for attribute names, and a dictionary of\n            placeholders for attribute values. Here is a sample return value:\n\n            ('#n0 = :v0', {'#n0': 'myattribute'}, {':v1': 'myvalue'})\n        \"\"\"\n        if not isinstance(condition, ConditionBase):\n            raise DynamoDBNeedsConditionError(condition)\n        attribute_name_placeholders = {}\n        attribute_value_placeholders = {}\n        condition_expression = self._build_expression(\n            condition,\n            attribute_name_placeholders,\n            attribute_value_placeholders,\n            is_key_condition=is_key_condition,\n        )\n        return BuiltConditionExpression(\n            condition_expression=condition_expression,\n            attribute_name_placeholders=attribute_name_placeholders,\n            attribute_value_placeholders=attribute_value_placeholders,\n        )\n\n    def _build_expression(\n        self,\n        condition,\n        attribute_name_placeholders,","sourceCodeStart":326,"sourceCodeEnd":362,"githubUrl":"https://github.com/boto/boto3/blob/6e10b029c1326a437932a8b24f38af69fd986e15/boto3/dynamodb/conditions.py#L326-L362","documentation":"When building a ConditionExpression or KeyConditionExpression, boto3 requires the top-level condition argument to be a ConditionBase. If you pass a raw attribute, scalar, list, or string to ConditionExpressionBuilder.build_condition, it raises DynamoDBNeedsConditionError(condition) because there is no defined serialization for non-condition input.","triggerScenarios":"Passing Attr('x') directly as filter_expression, passing a value like 'x = :v' as a hand-written string, or passing a dict/None where a ConditionBase is expected. Common when constructing Table.query(...) or Table.scan(...) conditions programmatically.","commonSituations":"Mixing boto3.dynamodb.conditions with raw string expressions; passing a Python value instead of Attr().eq(value); forgetting to call .eq()/.begins_with() on an attribute.","solutions":["Always pass a ConditionBase (result of Attr()/Key() comparison methods) to filter_expression / key_condition_expression.","If you want a string-based expression, do not use boto3 conditions; use the botocore-level ExpressionAttributeNames/Values with a raw string instead.","Validate dynamic conditions with isinstance(cond, ConditionBase) before passing them to the API."],"exampleFix":"# before\ntable.query(KeyConditionExpression=Key('pk'), ...)  # bare Key, no comparison\n# after\ntable.query(KeyConditionExpression=Key('pk').eq('user#42'), ...)","handlingStrategy":"type-guard","validationCode":"from boto3.dynamodb.conditions import ConditionBase\ndef assert_condition(c, label):\n    assert isinstance(c, ConditionBase), \\\n        f'{label} must be a ConditionBase; got {type(c).__name__}'\n    return c","typeGuard":"from boto3.dynamodb.conditions import ConditionBase\ndef is_condition_expression(v) -> bool:\n    return isinstance(v, ConditionBase)","tryCatchPattern":"from boto3.exceptions import DynamoDBNeedsConditionError\ntry:\n    table.scan(FilterExpression=expr)\nexcept DynamoDBNeedsConditionError:\n    expr = Attr('x').eq(1)  # rebuild properly","preventionTips":["Always build filter/key conditions from Attr()/Key() comparison methods.","Never pass raw strings or values as the condition expression.","Type-check conditions in dynamic builders before the API call."],"tags":["dynamodb","conditions","expression","boto3"],"backgroundTag":null,"analyzedSha":"6e10b029c1326a437932a8b24f38af69fd986e15","analyzedAt":"2026-08-11T20:52:47.213Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}