siyuan-note/siyuan · error

Field [ ] is required

Error message

Field [%s] is required

What it means

decodeExportFields in kernel/apicontract/export.go enforces required fields on export-style endpoints: when a field's value is missing or the JSON literal null and it is not marked optional, the decoder returns "Field [%s] is required". Export request contracts (e.g. export endpoints decoded via Decode/decodeExportFields) require certain inputs to function.

Solutions

1. Provide the required field named in the error with a valid value
2. Ensure the field is included even when empty if empty is meaningful for the endpoint
3. Update your client to the current API docs for the export endpoint
4. If the field genuinely is optional for your use, check whether the contract marks it optional and upgrade SiYuan or adjust the call

Example fix

// before
const payload = {}; // id omitted
// after
const payload = { id: blockId };

function requireFields(payload, names) {
  for (const n of names) {
    if (payload[n] === undefined || payload[n] === null) throw new Error(`Field [${n}] is required`);
  }
}
requireFields(payload, ["id"]);

const hasRequired = (o, n) => o[n] !== undefined && o[n] !== null;

try { await exportApi(payload); } catch (e) { const m = String(e).match(/Field \[(\w+)\] is required/); if (m) return alert(`Missing field: ${m[1]}`); throw e; }

When it happens

Trigger: Calling an export API (e.g. /api/export/*) without a required field such as id/pth, or sending it as null; multipart or form bodies missing the field; clients dropping empty-string fields from the payload entirely when the field is required.

Common situations: Export-to-PDF/Word/image integrations that build payloads conditionally and skip empty values; plugin upgrades where a field was added as required after the plugin was written; template code with commented-out fields.

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 [ ] must not be empty
• Field [ ] should be of type [ ]
• AI editor action must not be empty
• block [ ] type is locked: expected , got
• block swap requires two non-document blocks

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

Appendix: source

Thrown at kernel/apicontract/export.go:241

			var entries []json.RawMessage
			var values []string
			if json.Unmarshal(fields[name], &entries) == nil {
				for _, entry := range entries {
					var text string
					if json.Unmarshal(entry, &text) == nil && text != "" {
						values = append(values, text)
					}
				}
			}
			dest.Set(reflect.ValueOf(values))
			continue
		}
		raw := fields[name]
		if len(raw) == 0 || bytes.Equal(bytes.TrimSpace(raw), []byte("null")) {
			if has("optional") {
				continue
			}
			return fmt.Errorf("Field [%s] is required", name)
		}
		if err := decodeRequestValue(raw, dest); err != nil {
			if has("ignoretype") || value.Type() == reflect.TypeFor[ExportTitleOptions]() && name == "addTitle" {
				dest.SetZero()
				continue
			}
			kind := dest.Kind()
			if kind == reflect.Pointer {
				kind = dest.Type().Elem().Kind()
			}
			kindName := map[reflect.Kind]string{reflect.String: "String", reflect.Bool: "Boolean", reflect.Float64: "Number", reflect.Slice: "Array"}[kind]
			return fmt.Errorf("Field [%s] should be of type [%s]", name, kindName)
		}
		if has("trim") {
			text := strings.TrimSpace(dest.String())
			if text == "" {
				return fmt.Errorf("Field [%s] must not be empty", name)
			}

View on GitHub (pinned to 9f775e8a12)