What causes "attribute view embedded base is missing" in siyuan-note/siyuan?

Add an anonymous embedded pointer field (e.g. *AVLayoutTable) to the struct

attribute view embedded base is missing

Error message

attribute view embedded base is missing

What it means

avEmbeddedPayloadSchema builds the JSON schema for struct types that must embed exactly one anonymous pointer base type (e.g. *AVLayoutTable). The anonymous pointer field carries the optional inherited fields; if the type registered for schema generation has no such embedded pointer field, the builder cannot model the embedded-present/embedded-absent anyOf and returns this error.

Solutions

Add an anonymous embedded pointer field (e.g. *AVLayoutTable) to the struct
Verify the struct is registered in the correct schema path (embedded vs regular payload schema)
Regenerate API contracts and run kernel apicontract tests after changing the struct shape

Example fix

// before
type AVViewTableColumn struct {
    Width int `json:"width"`
}
// after
type AVViewTableColumn struct {
    *AVLayoutTable
    Width int `json:"width"`
}

Defensive patterns

Strategy: validation

Validate before calling

// verify the struct has exactly one anonymous embedded pointer before registering
for i := 0; i < t.NumField(); i++ {
    f := t.Field(i)
    if f.Anonymous && f.Type.Kind() == reflect.Pointer {
        fmt.Println("embedded base found:", f.Type.Elem().Name())
    }
}

Try / catch

schema, err := avPayloadSchema(b, t, input)
if err != nil {
    return nil, fmt.Errorf("build schema for %s: %w", t.Name(), err)
}

Prevention

Every type in the embedded-schema switch must embed one anonymous pointer base
Run go test ./apicontract/... after adding or reshaping AV structs
Regenerate contract schemas rather than hand-editing them

When it happens

Trigger: Adding a new struct to the avEmbeddedPayloadSchema switch (or one matching its type list) that lacks an anonymous embedded pointer field, or changing an existing type's embedded field to a named/non-pointer field so the reflect scan finds no candidate.

Common situations: Developer defines a new layout wrapper struct and forgets the embedded *AVLayoutXxx base; refactoring flattens the embedding; a type is copied from a non-embedded style and registered in the same schema path.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/1672cf994eff53bf. Report an issue: GitHub.

Appendix: source

Thrown at kernel/apicontract/av_union.go:97

func avEmbeddedPayloadSchema(b *schemaBuilder, t reflect.Type, input bool) (*Schema, error) {
	name := t.Name()
	if _, ok := b.definitions[name]; ok {
		return &Schema{Ref: "#/$defs/" + name}, nil
	}
	result := &Schema{}
	b.definitions[name] = result
	var base reflect.Type
	var own []reflect.StructField
	for i := 0; i < t.NumField(); i++ {
		field := t.Field(i)
		if field.Anonymous && field.Type.Kind() == reflect.Pointer {
			base = field.Type.Elem()
		} else {
			own = append(own, field)
		}
	}
	if base == nil {
		return nil, errors.New("attribute view embedded base is missing")
	}
	for _, present := range []bool{true, false} {
		fields := append([]reflect.StructField{}, own...)
		if present {
			for i := 0; i < base.NumField(); i++ {
				field := base.Field(i)
				shadowed := false
				for _, child := range own {
					if child.Name == field.Name {
						shadowed = true
						break
					}
				}
				if !shadowed {
					fields = append(fields, field)
				}
			}
		}

View on GitHub (pinned to 9f775e8a12)