usememos/memos · error

generalSetting must be populated for key GENERAL

Error message

generalSetting must be populated for key GENERAL

What it means

Thrown when an instance-setting deployment file (memos-instance-setting-*.json) declares "key": "GENERAL" but carries no generalSetting message (setting.GetGeneralSetting() == nil). The oneof payload must match the declared key; an empty or mismatched payload means the setting would be a no-op, so validation fails and the file is reported as an invalid instance setting deployment file at startup.

Source

Thrown at store/deployment_config.go:226

	if len(config.Scopes) == 0 {
		return errors.New("config.oauth2Config.scopes is required")
	}
	for i, scope := range config.Scopes {
		if strings.TrimSpace(scope) == "" {
			return errors.Errorf("config.oauth2Config.scopes[%d] must not be empty", i)
		}
	}
	if config.FieldMapping == nil || strings.TrimSpace(config.FieldMapping.Identifier) == "" {
		return errors.New("config.oauth2Config.fieldMapping.identifier is required")
	}
	return nil
}

func validateAndNormalizeDeploymentInstanceSetting(setting *storepb.InstanceSetting) error {
	switch setting.Key {
	case storepb.InstanceSettingKey_GENERAL:
		if setting.GetGeneralSetting() == nil {
			return errors.New("generalSetting must be populated for key GENERAL")
		}
		if offset := setting.GetGeneralSetting().WeekStartDayOffset; offset < -1 || offset > 6 {
			return errors.New("generalSetting.weekStartDayOffset must be between -1 and 6")
		}
	case storepb.InstanceSettingKey_STORAGE:
		storage := setting.GetStorageSetting()
		if storage == nil {
			return errors.New("storageSetting must be populated for key STORAGE")
		}
		// Normalization would silently self-heal this misconfiguration to LOCAL;
		// a deployment file declaring S3 without a config should fail loudly.
		if storage.StorageType == storepb.InstanceStorageSetting_S3 && storage.S3Config == nil && len(storage.Storages) == 0 {
			return errors.New("storageSetting.s3Config is required for S3")
		}
		NormalizeInstanceStorageSetting(storage)
		if storage.UploadSizeLimitMb < 0 {
			return errors.New("storageSetting.uploadSizeLimitMb must not be negative")
		}

View on GitHub (pinned to 14d757ce1f)

Solutions

1. Add a "generalSetting" object matching the declared key, e.g. { "key": "GENERAL", "generalSetting": { "weekStartDayOffset": 0 } }.
2. Verify the payload field name is exactly generalSetting (lowerCamelCase protojson).
3. If you meant a different setting, change "key" and the payload together.

Example fix

// before
{ "key": "GENERAL" }

// after
{ "key": "GENERAL", "generalSetting": { "weekStartDayOffset": 1 } }

if setting.Key == storepb.InstanceSettingKey_GENERAL && setting.GetGeneralSetting() == nil {
    return errors.New("GENERAL setting requires a generalSetting payload")
}

func payloadMatchesKey(s *storepb.InstanceSetting) bool {
    switch s.GetKey() {
    case storepb.InstanceSettingKey_GENERAL:
        return s.GetGeneralSetting() != nil
    default:
        return false
    }
}

When it happens

Trigger: A memos-instance-setting-general.json containing only { "key": "GENERAL" }, or whose payload key is spelled differently (e.g. "general_setting", "general") so protojson leaves the oneof unset.

Common situations: Authoring the file from a proto dump where the payload key got dropped; using snake_case field names inconsistent with protojson; intending to configure a different key but leaving "key": "GENERAL".

Related errors

• generalSetting.weekStartDayOffset must be between -1 and 6
• storageSetting must be populated for key STORAGE
• memoRelatedSetting must be populated for key MEMO_RELATED
• notificationSetting must be populated for key NOTIFICATION
• aiSetting must be populated for key AI

AI-assisted analysis of usememos/memos@14d757ce1f (2026-08-15). Data as JSON: /api/errors/6584a4f3cc4c8024. Report an issue: GitHub.