What causes "email value is missing" in siyuan-note/siyuan?

Ensure the value JSON includes a non-null email object, e.g. {"email": {"content": "user@example.com"}}

email value is missing

Error message

email value is missing

What it means

Thrown inside normalizeNewItemTemplateValue (kernel/av/new_item_template.go:392-393) when key.Type == KeyTypeEmail but value.Email is nil. The function clones the incoming Value and then strips every non-email sub-field to nil, so it requires a non-nil *ValueEmail payload to proceed. Without it the template field cannot produce a meaningful default. The strict caller at line 332 wraps this as "new item template field [<keyID>] value is invalid: email value is missing" and returns it to the API; the prune caller at line 258 silently deletes the field instead.

Source

Thrown at kernel/av/new_item_template.go:393

		var selections []*ValueSelect
		for _, selection := range value.MSelect {
			if nil != selection && "" != strings.TrimSpace(selection.Content) {
				selections = append(selections, selection)
			}
		}
		if KeyTypeSelect == key.Type && 1 < len(selections) {
			selections = selections[:1]
		}
		value.MSelect = selections
		value.Text, value.Number, value.Date, value.URL, value.Email, value.Phone, value.MAsset, value.Checkbox, value.Relation = nil, nil, nil, nil, nil, nil, nil, nil, nil
	case KeyTypeURL:
		if nil == value.URL {
			return nil, errors.New("URL value is missing")
		}
		value.Text, value.Number, value.Date, value.MSelect, value.Email, value.Phone, value.MAsset, value.Checkbox, value.Relation = nil, nil, nil, nil, nil, nil, nil, nil, nil
	case KeyTypeEmail:
		if nil == value.Email {
			return nil, errors.New("email value is missing")
		}
		value.Text, value.Number, value.Date, value.MSelect, value.URL, value.Phone, value.MAsset, value.Checkbox, value.Relation = nil, nil, nil, nil, nil, nil, nil, nil, nil
	case KeyTypePhone:
		if nil == value.Phone {
			return nil, errors.New("phone value is missing")
		}
		value.Text, value.Number, value.Date, value.MSelect, value.URL, value.Email, value.MAsset, value.Checkbox, value.Relation = nil, nil, nil, nil, nil, nil, nil, nil, nil
	case KeyTypeMAsset:
		var assets []*ValueAsset
		for _, asset := range value.MAsset {
			if nil != asset && "" != strings.TrimSpace(asset.Content) {
				if AssetTypeFile != asset.Type && AssetTypeImage != asset.Type {
					return nil, fmt.Errorf("invalid asset type [%s]", asset.Type)
				}
				assets = append(assets, asset)
			}
		}
		value.MAsset = assets

View on GitHub (pinned to 251596fc0d)

Solutions

Ensure the value JSON includes a non-null email object, e.g. {"email": {"content": "user@example.com"}}
If no default email is desired, omit the field from the template FieldValues map entirely rather than sending a Value with a nil Email
Construct the value programmatically with Value.Email = &ValueEmail{Content: "..."} before persisting

Example fix

// before
fieldValue.Value = &av.Value{Type: av.KeyTypeEmail}
// after
fieldValue.Value = &av.Value{Type: av.KeyTypeEmail, Email: &av.ValueEmail{Content: "user@example.com"}}

Defensive patterns

Strategy: validation

Validate before calling

// Before calling normalizeNewItemTemplateValue or saving a template:
func validateEmailValue(value *av.Value, key *av.Key) error {
    if key.Type == av.KeyTypeEmail && value.Email == nil {
        return fmt.Errorf("email key requires a non-nil Value.Email")
    }
    return nil
}

Type guard

func hasEmailValue(v *av.Value) bool {
    return v != nil && v.Email != nil
}

Prevention

Always populate the type-specific sub-field that matches the key type before saving a template value
When building template values programmatically, use a factory function that sets the correct sub-field per key type
Omit fields from FieldValues entirely if no default value is needed, rather than sending nil sub-fields

When it happens

Trigger: Saving an Attribute View new-item template (e.g. via the AV set/save API) where a FieldValues entry has Mode = NewItemFieldValueStatic, the key type is "email", but the Value JSON omits the "email" key or sets it to null.

Common situations: Programmatic AV template creation that reuses one generic Value struct across multiple field types; migrating from an AV schema version that predates email fields; frontend sending a partial value object that only populates some sub-fields.

Related errors

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/3869d38821e82c0e. Report an issue: GitHub.