siyuan-note/siyuan · error

Field [ ] is required

Error message

Field [%s] is required

What it means

avDecodeBoundFields handles attribute-view endpoints whose structurally complex fields are bound to placeholders during generic decoding, then re-decoded individually. Every name listed in boundFields must be present in the request; a missing field aborts decoding with 'Field [<name>] is required'.

Solutions

1. Add the required field with its proper JSON value (object for value/group, array for data/values/blocksValues)
2. Check the endpoint's contract in docs/API-CONTRACTS.md for the exact required field name
3. Fix field-name typos in the client payload

Example fix

// before
fetchPost("/api/av/setAttrViewFilters", {avID: "20240101"});
// after
fetchPost("/api/av/setAttrViewFilters", {avID: "20240101", data: []});

const REQUIRED = {setAttrViewGroup:["group"],setAttrViewFilters:["data"],setAttrViewSorts:["data"],appendAttributeViewDetachedBlocksWithValues:["blocksValues"],setAttributeViewBlockAttr:["value"],batchSetAttributeViewBlockAttrs:["values"]};
function assertBound(endpoint, payload) { for (const f of REQUIRED[endpoint] ?? []) if (!(f in payload)) throw new Error(`Field [${f}] is required`); }

const hasField = (obj, name) => obj != null && Object.prototype.hasOwnProperty.call(obj, name);

try { await post(avEndpoint, payload); } catch (e) { if (/is required/.test(e.message)) { console.error("missing field:", e.message); } else throw e; }

When it happens

Trigger: Calls to endpoints like /api/av/setAttrViewGroup (group), /api/av/setAttrViewFilters and setAttrViewSorts (data), appendAttributeViewDetachedBlocksWithValues (blocksValues), setAttributeViewBlockAttr (value), batchSetAttributeViewBlockAttrs (values) where the named field is omitted from the JSON body.

Common situations: Third-party plugin/API scripts migrating between SiYuan API versions with changed payload shapes, partial request objects built conditionally, typos in field names (e.g. 'value' vs 'values').

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• config must contain exactly one setting; use separate calls…
• Field [keyIDs] is required
• field name must not be empty
• invalid width for attribute view column
• numberFormat requires a number field and a supported format

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

Appendix: source

Thrown at kernel/apicontract/av_decode.go:22

	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"reflect"
	"strings"
)

// avDecodeBoundFields 仅对原本经过 JSON 结构体绑定的字段保留大小写匹配和数字归一化。
func avDecodeBoundFields[Request any](reader io.Reader, path string, boundFields map[string]string, ignoredBools []string) (request Request, err error) {
	fields, err := blockRequestFields(reader, path)
	if err != nil {
		return request, err
	}
	original := map[string]json.RawMessage{}
	for name, placeholder := range boundFields {
		raw, present := fields[name]
		if !present {
			return request, fmt.Errorf("Field [%s] is required", name)
		}
		if bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
			return request, fmt.Errorf("Field [%s] must not be null", name)
		}
		original[name] = raw
		fields[name] = json.RawMessage(placeholder)
	}
	for _, name := range ignoredBools {
		original[name] = fields[name]
		delete(fields, name)
	}
	value := reflect.ValueOf(&request).Elem()
	if err = decodeRequestFields(value, fields); err != nil {
		return request, err
	}
	for i := 0; i < value.NumField(); i++ {
		field := value.Type().Field(i)
		name := field.Tag.Get("json")

View on GitHub (pinned to 9f775e8a12)