{"record":{"id":"7e6d43e8f24f3f73","repo":"microsoft/aspire","slug":"invalid-referenceexpression-must-have-either-handle","errorCode":null,"errorMessage":"Invalid ReferenceExpression: must have either handle, condition, or format","messagePattern":"Invalid ReferenceExpression: must have either handle, condition, or format","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.CodeGeneration.Python/PythonModuleBuilder.cs","lineNumber":1418,"sourceCode":"                if self._condition and self._when_true and self._when_false and self._match_value is not None:\n                    return {\n                        \"$expr\": {\n                            \"condition\": self._condition,\n                            \"whenTrue\": self._when_true.to_json(),\n                            \"whenFalse\": self._when_false.to_json(),\n                            \"matchValue\": self._match_value,\n                        }\n                    }\n                if self._format:\n                    result: dict[str, typing.Any] = {\n                        \"$expr\": {\n                            \"format\": self._format,\n                        }\n                    }\n                    if self._value_providers:\n                        result[\"$expr\"][\"valueProviders\"] = self._value_providers\n                    return result\n                raise ValueError(\"Invalid ReferenceExpression: must have either handle, condition, or format\")\n\n            def __repr__(self) -> str:\n                if self._handle:\n                    return f\"ReferenceExpression(handle={self._handle.handle_id})\"\n                if self._condition:\n                    return \"ReferenceExpression(conditional)\"\n                return f\"ReferenceExpression(formattedString)\"\n\n\n        def _extract_handle_for_expr(value: typing.Any) -> typing.Any:\n            '''\n            Extracts a value for use in reference expressions.\n            Supports handles (objects) and string literals.\n            '''\n            if value is None:\n                raise ValueError(\"Cannot use None in reference expression\")\n\n            # String literals - include directly in the expression","sourceCodeStart":1400,"sourceCodeEnd":1436,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.CodeGeneration.Python/PythonModuleBuilder.cs#L1400-L1436","documentation":"ReferenceExpression validation raises ValueError('Invalid ReferenceExpression: must have either handle, condition, or format') when serializing an expression that has none of the three supported forms: a resource handle, a condition, or a format/template. A ReferenceExpression must encode at least one of these to be a meaningful expression the AppHost can evaluate.","triggerScenarios":"Creating a ReferenceExpression (directly or via helpers) with no handle, no condition, and no format string set, then using it in a resource definition or serializing it to the transport payload.","commonSituations":"Building an expression manually with all-empty kwargs; a helper returning a bare ReferenceExpression on a code path that forgot to set format/handle; refactors removing the format argument while leaving the object empty; conditional logic that leaves handle=None and condition=None.","solutions":["Pass a format string (string_expr or format kwarg) when the expression is a literal/template.","Attach a resource handle (handle=...) when the expression should reference a resource value.","Add a condition (condition=...) for conditional expressions.","Guard your builder code so it never constructs a ReferenceExpression without at least one of the three."],"exampleFix":"// before\nexpr = ReferenceExpression()  # nothing set\n// after\nexpr = string_expr(\"{value}\", value=\"fallback\")  # or ReferenceExpression(handle=resource_handle)","handlingStrategy":"validation","validationCode":"def valid_expression(expr) -> bool:\n    return bool(expr._handle or expr._condition or expr._format)","typeGuard":"def is_usable_expression(expr) -> bool:\n    return bool(getattr(expr, '_handle', None) or getattr(expr, '_condition', None) or getattr(expr, '_format', None))","tryCatchPattern":"try:\n    payload = expr.to_transport()\nexcept ValueError as e:\n    if 'Invalid ReferenceExpression' in str(e):\n        expr = string_expr('{value}', value=default_value)\n    else:\n        raise","preventionTips":["Never construct ReferenceExpression directly without handle/condition/format","Prefer helpers like string_expr that always produce a valid expression","Assert expression validity in builder code before serialization"],"tags":["python","reference-expression","validation","value-error"],"backgroundTag":"missing-required-argument","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}