siyuan-note/siyuan · error

Field [ ] is required

Error message

Field [%s] is required

What it means

legacyField is the shared legacy-request field decoder used across apicontract handlers. When a field marked required=true is absent from the fields map (zero-length raw bytes) or explicitly null, it fails with 'Field [<key>] is required'. This is the generic missing-required-field error for all endpoints still routed through legacy decoding.

Solutions

1. Add the named field (given in the message) to the request body
2. Replace null values for required fields with actual values
3. Check field name spelling and casing against the API contract docs
4. Update the client to the current API version if the field was recently made required

Example fix

// before
{"id": "20240101120000-abcdef1"}
// after
{"id": "20240101120000-abcdef1", "type": "id"}

const REQUIRED = ["id", "type"];
for (const k of REQUIRED) {
  if (body[k] === undefined || body[k] === null) throw new Error(`Field [${k}] is required`);
}

try {
  const resp = await fetch(url, {method: "POST", body: JSON.stringify(body)});
  const out = await resp.json();
} catch (e) {
  if (String(e).includes("is required")) {
    console.error("Missing required field:", e.message); // parse key from [key]
  } else {
    throw e;
  }
}

When it happens

Trigger: Any legacy-decoded endpoint call (SetInlineStyles, AI string params, attribute-view parsed requests, bazaar strings, copyFiles, DocVersionRef decoding, graph requests) omitting a required key or passing null for it.

Common situations: Hand-written scripts calling the kernel HTTP API and missing a field; older clients after a contract added a new required field; templated payloads with unfilled placeholders resolving to null.

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

• Field [conf] is required
• Field [id] should be of type [String]
• Field [notebook] is required
• left document version is required
• [paths] is required

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

Appendix: source

Thrown at kernel/apicontract/inline_style_input.go:44

// legacyJSONValue 保留先解析通用 JSON 再绑定结构体时的数字归一化和大小写匹配。
func legacyJSONValue[T any](raw []byte) (value T, err error) {
	var normalized any
	if err = json.Unmarshal(raw, &normalized); err != nil {
		return
	}
	data, err := json.Marshal(normalized)
	if err == nil {
		err = json.Unmarshal(data, &value)
	}
	return
}

func legacyField[T any](fields map[string]json.RawMessage, key, kind string, required bool) (value T, err error) {
	raw := fields[key]
	if len(raw) == 0 || bytes.Equal(raw, []byte("null")) {
		if required {
			err = fmt.Errorf("Field [%s] is required", key)
		}
		return
	}
	if json.Unmarshal(raw, &value) != nil {
		err = fmt.Errorf("Field [%s] should be of type [%s]", key, kind)
	}
	return
}

func init() {
	SetInlineStyles.decodeRequest = func(reader io.Reader) (request SetInlineStylesRequest, err error) {
		fields, err := blockRequestFields(reader, "/api/storage/setInlineStyles")
		if err != nil {
			return request, err
		}
		version, err := legacyField[float64](fields, "version", "Number", true)
		if err != nil {
			return request, err

View on GitHub (pinned to 9f775e8a12)