siyuan-note/siyuan · error

[modes] is required ([0] for light, [1] for dark, [0,1] for…

Error message

[modes] is required ([0] for light, [1] for dark, [0,1] for both)

What it means

The SetTheme request decoder collects theme modes (0=light, 1=dark) from the 'modes' array, discarding invalid entries. If no valid mode survives, it fails with this message because the theme cannot be set without at least one mode.

Solutions

1. Send modes as [0], [1], or [0,1] in the request JSON
2. Map symbolic names to codes before sending (light->0, dark->1)
3. Ensure each entry is a JSON number, not a string
4. Check the array length is > 0 client-side

Example fix

// before
body: JSON.stringify({ modes: [] })
// after
body: JSON.stringify({ modes: [0, 1] })

function validModes(modes: unknown[]): number[] {
  const out = modes.filter((m): m is number => m === 0 || m === 1);
  if (out.length === 0) throw new Error('modes must include 0 (light) and/or 1 (dark)');
  return out;
}

function isThemeMode(v: unknown): v is 0 | 1 { return v === 0 || v === 1; }

try { await setTheme(modes); } catch (e) { if (String(e).includes('[modes] is required')) { fallbackModes = [0, 1]; retry(fallbackModes); } }

When it happens

Trigger: Calling the SetTheme endpoint with modes missing, an empty array, an array of only invalid values (non-integers or integers other than 0/1), or entries in the wrong JSON type (strings "0","1").

Common situations: Clients sending mode names ('light'/'dark') instead of numeric codes, sending an empty modes array to 'unset' theme, or theme switcher code building the array from bad config state.

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

• ErrInvalidColumnAlign
• Field [mode] must be 0 or 1
• Field [ ] has an invalid value
• Field [ ] must not be empty
• Field [srcs] must not be empty

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

Appendix: source

Thrown at kernel/apicontract/setting_config.go:150

			return
		}
		r.Theme, r.AppearanceMode = strings.TrimSpace(r.Theme), strings.TrimSpace(r.AppearanceMode)
		r.Modes = make([]float64, 0, 2)
		if r.Theme == "" {
			return
		}
		for _, raw := range modes {
			var value float64
			if bytes.Equal(raw, []byte("null")) || json.Unmarshal(raw, &value) != nil {
				break
			}
			if mode := int(value); mode != 0 && mode != 1 {
				break
			}
			r.Modes = append(r.Modes, value)
		}
		if len(r.Modes) == 0 {
			err = errors.New("[modes] is required ([0] for light, [1] for dark, [0,1] for both)")
		}
		return
	}
}

View on GitHub (pinned to 9f775e8a12)