cube-js/cube · error · TemplateException

unable to register variable: name '%s' is already in use for

Error message

unable to register variable: name '%s' is already in use for function

What it means

add_variable() refuses to register a variable whose name is already taken by a registered function, because the template engine resolves names unambiguously between the two namespaces. This is an early conflict check to prevent silent shadowing.

Source

Thrown at packages/cubejs-backend-native/python/cube/src/__init__.py:187

class TemplateContext:
    functions: dict[str, Callable]
    variables: dict[str, Any]
    filters: dict[str, Callable]

    def __init__(self):
        self.functions = {}
        self.variables = {}
        self.filters = {}

    def add_function(self, name, func):
        if not callable(func):
            raise TemplateException("function registration must be used with functions, actual: '%s'" % type(func).__name__)

        self.functions[name] = func

    def add_variable(self, name, val):
        if name in self.functions:
            raise TemplateException("unable to register variable: name '%s' is already in use for function" % name)

        self.variables[name] = val

    def add_filter(self, name, func):
        if not callable(func):
            raise TemplateException("function registration must be used with functions, actual: '%s'" % type(func).__name__)

        self.filters[name] = func

    def function(self, func):
        if isinstance(func, str):
            return TemplateFunctionRef(self, func)

        self.add_function(func.__name__, func)
        return func

    def filter(self, func):
        if isinstance(func, str):

View on GitHub (pinned to 7d981676b3)

Solutions

Rename the variable to a name not used by any function.
Rename or remove the conflicting function registration if the variable should take precedence.
Track registered names before registering to detect collisions in dynamic code.

Example fix

// before
template.add_function('now', get_now)
template.add_variable('now', '2024-01-01')  # conflict
// after
template.add_function('now_fn', get_now)
template.add_variable('now', '2024-01-01')

Defensive patterns

Strategy: validation

Validate before calling

if name in template.functions:
    raise ValueError(f"'{name}' already registered as a function")
template.add_variable(name, val)

Try / catch

try:
    template.add_variable(name, val)
except TemplateException:
    template.add_variable(name + '_var', val)  # or choose another name

Prevention

Keep separate naming prefixes for functions vs variables
Check existing registrations before dynamic registration
Centralize name registration in one helper that deconflicts

When it happens

Trigger: Calling Template.add_variable(name, val) after add_function(name, ...) with the same name string.

Common situations: Large templates where functions and variables share naming conventions (e.g. 'now'), dynamic registration loops that collide, refactors that renamed one side but not the other.

Related errors

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/c782be17c81644dd. Report an issue: GitHub.