lancedb/lancedb · error · ValueError

Variable names cannot contain colons

Error message

Variable names cannot contain colons

What it means

The embedding registry lets you define named variables (e.g. for API keys or runtime flags) via set_var. Variable names are joined with colons in the registry's name syntax, so a colon in a name would corrupt that syntax; the library rejects such names with ValueError at registration time.

Solutions

1. Remove the colon from the variable name, e.g. use 'openai_key' or 'openai-key' instead of 'openai:key'
2. Keep any ':' only in the value, which is allowed
3. If namespacing is needed, encode it without colons, e.g. use '__' or '/' separators

Example fix

// before
registry.set_var("openai:key", "sk-...")
// after
registry.set_var("openai_key", "sk-...")

def valid_var_name(name: str) -> bool:
    return isinstance(name, str) and ":" not in name and len(name) > 0

if not valid_var_name(name):
    raise ValueError(f"Variable name '{name}' must not contain ':'")
registry.set_var(name, value)

When it happens

Trigger: Calling registry.set_var(name, value) where the name string contains ':' (e.g. set_var('openai:key', ...)).

Common situations: Developers try to namespace variables like 'provider:key' or pass full 'VAR:value' strings copied from docs or env-var strings.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• a Function environment is pip or conda, not both
• All elements in vector_results should be of the same type
• All elements in vector_results should be of the same type
• All elements in vector_results should be of the same type
• blocks_per_epoch='auto' cannot estimate an empty dataset

AI-assisted analysis of lancedb/lancedb@c7b051aff7 (2026-09-08). Data as JSON: /api/errors/f29ec54e2fd2e9b5. Report an issue: GitHub.

Appendix: source

Thrown at python/python/lancedb/embeddings/registry.py:173

        # Note that metadata dictionary values must be bytes
        # so we need to json dump then utf8 encode
        metadata = json.dumps(json_data, indent=2).encode("utf-8")
        return {"embedding_functions": metadata}

    def set_var(self, name: str, value: str) -> None:
        """
        Set a variable. These can be accessed in embedding configuration using
        the syntax `$var:variable_name`. If they are not set, an error will be
        thrown letting you know which variable is missing. If you want to supply
        a default value, you can add an additional part in the configuration
        like so: `$var:variable_name:default_value`. Default values can be
        used for runtime configurations that are not sensitive, such as
        whether to use a GPU for inference.

        The name must not contain a colon. Default values can contain colons.
        """
        if ":" in name:
            raise ValueError("Variable names cannot contain colons")
        self._variables[name] = value

    def get_var(self, name: str) -> str:
        """
        Get a variable.
        """
        return self._variables[name]


# Global instance
__REGISTRY__ = EmbeddingFunctionRegistry()


# @EmbeddingFunctionRegistry.get_instance().register(name) doesn't work in 3.8
def register(name):
    return __REGISTRY__.get_instance().register(name)

View on GitHub (pinned to c7b051aff7)