microsoft/aspire · error · ValueError

Invalid ReferenceExpression: must have either handle…

Error message

Invalid ReferenceExpression: must have either handle, condition, or format

What it means

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.

Solutions

1. Pass a format string (string_expr or format kwarg) when the expression is a literal/template.
2. Attach a resource handle (handle=...) when the expression should reference a resource value.
3. Add a condition (condition=...) for conditional expressions.
4. Guard your builder code so it never constructs a ReferenceExpression without at least one of the three.

Example fix

// before
expr = ReferenceExpression()  # nothing set
// after
expr = string_expr("{value}", value="fallback")  # or ReferenceExpression(handle=resource_handle)

def valid_expression(expr) -> bool:
    return bool(expr._handle or expr._condition or expr._format)

def is_usable_expression(expr) -> bool:
    return bool(getattr(expr, '_handle', None) or getattr(expr, '_condition', None) or getattr(expr, '_format', None))

try:
    payload = expr.to_transport()
except ValueError as e:
    if 'Invalid ReferenceExpression' in str(e):
        expr = string_expr('{value}', value=default_value)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Cannot use None in reference expression
• Cannot use value of type
• Cannot use null or undefined in reference expression
• no input with name ' ' was found
• -32602

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/7e6d43e8f24f3f73. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.Python/PythonModuleBuilder.cs:1418

                if self._condition and self._when_true and self._when_false and self._match_value is not None:
                    return {
                        "$expr": {
                            "condition": self._condition,
                            "whenTrue": self._when_true.to_json(),
                            "whenFalse": self._when_false.to_json(),
                            "matchValue": self._match_value,
                        }
                    }
                if self._format:
                    result: dict[str, typing.Any] = {
                        "$expr": {
                            "format": self._format,
                        }
                    }
                    if self._value_providers:
                        result["$expr"]["valueProviders"] = self._value_providers
                    return result
                raise ValueError("Invalid ReferenceExpression: must have either handle, condition, or format")

            def __repr__(self) -> str:
                if self._handle:
                    return f"ReferenceExpression(handle={self._handle.handle_id})"
                if self._condition:
                    return "ReferenceExpression(conditional)"
                return f"ReferenceExpression(formattedString)"


        def _extract_handle_for_expr(value: typing.Any) -> typing.Any:
            '''
            Extracts a value for use in reference expressions.
            Supports handles (objects) and string literals.
            '''
            if value is None:
                raise ValueError("Cannot use None in reference expression")

            # String literals - include directly in the expression

View on GitHub (pinned to 25830f84bd)