BoundaryML/baml · error

error decoding value, type alias not found:

Error message

error decoding value, type alias not found: 

What it means

While converting a CFFI type descriptor to a Go type, the decoder resolves a TypeAliasType by looking up "<namespace>.<name>" in the TypeMap. This panic means the type alias referenced by the Rust engine is not present in the Go TypeMap — usually because the Go client was generated before the alias was added or renamed in the .baml file.

Source

Thrown at engine/language_client_go/baml_go/serde/decode.go:460

		return reflect.SliceOf(goElementType)
	}

	if map_, ok := type_.(*cffi.CFFIFieldTypeHolder_MapType); ok {
		mapType := map_.MapType
		goKeyType := convertFieldTypeToGoType(mapType.KeyType, typeMap)
		goValueType := convertFieldTypeToGoType(mapType.ValueType, typeMap)
		if goValueType == typeMap.typeMap["INTERNAL.nil"] {
			return reflect.TypeOf(map[string]any{})
		}
		return reflect.MapOf(goKeyType, goValueType)
	}

	if typeAlias, ok := type_.(*cffi.CFFIFieldTypeHolder_TypeAliasType); ok {
		name := typeAlias.TypeAliasType.Name.Name
		namespace := typeAlias.TypeAliasType.Name.Namespace.String()
		goType, ok := typeMap.typeMap[namespace+"."+name]
		if !ok {
			panic("error decoding value, type alias not found: " + namespace + "." + name)
		}
		return goType
	}

	// any is weird in go, (alias for interface{})
	if _, ok := type_.(*cffi.CFFIFieldTypeHolder_NullType); ok {
		if _, ok := typeMap.typeMap["INTERNAL.nil"]; ok {
			return reflect.TypeOf((*interface{})(nil)).Elem()
		}
		return reflect.TypeOf((*interface{})(nil))
	}
	if _, ok := type_.(*cffi.CFFIFieldTypeHolder_AnyType); ok {
		return reflect.TypeOf((*interface{})(nil)).Elem()
	}

	panic("error decoding value, unknown field type: " + fmt.Sprintf("%+v", fieldType))
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Run `baml-cli generate` to regenerate the Go client so the TypeMap includes the alias under the expected namespace.name key
2. Verify the alias name/namespace in the .baml file matches what was generated (rename it back or regenerate after renames)
3. Align baml CLI and Go runtime dependency versions (go get -u github.com/boundaryml/baml/... and reinstall the CLI)
4. If a dynamic fallback is desired, check whether your baml version supports dynamic types and register the alias in the TypeMap when constructing it

Example fix

// before (baml): alias added but Go client stale
type Price = int | float

// after: regenerate
// terminal:
// baml-cli generate  # TypeMap now contains "baml.Price" -> generated Go type
// then rebuild the Go app

// Pre-check that every alias used in baml_src exists in the generated TypeMap
func validateAliases(tm baml_go.TypeMap, aliases []string) error {
	for _, a := range aliases {
		if _, ok := tm.TypeMap[a]; !ok {
			return fmt.Errorf("type alias %q missing from generated client — run baml-cli generate", a)
		}
	}
	return nil
}

When it happens

Trigger: Decoding a value whose declared type is a BAML type alias (type Foo = ...) that the generated TypeMap does not contain, e.g. after adding `type MyAlias = string | int` to the baml file without regenerating the Go client, or when the alias namespace from the engine does not match the generated map keys.

Common situations: Renaming or adding type aliases in .baml files and running old generated code; multiple baml projects where an alias namespace differs from the generated Go package namespace; version skew between the baml runtime and CLI.

Related errors

• error decoding type, checked type not found:
• error decoding value, unknown field type:
• error decoding value, unknown literal type:
• ObjectValue is not yet supported:
• error decoding value:

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/4bfcbb96c070b628. Report an issue: GitHub.