usememos/memos · error

storageSetting must be populated for key STORAGE

Error message

storageSetting must be populated for key STORAGE

What it means

Thrown when an instance-setting deployment file declares "key": "STORAGE" but the storageSetting payload message is absent (GetStorageSetting() == nil). The key/payload pair must be consistent; a STORAGE setting with no payload cannot express a storage type or upload limit, so the loader fails with 'invalid instance setting deployment file' at startup.

Source

Thrown at store/deployment_config.go:234

	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")
		}
		defaultStorage := GetDefaultStorage(storage)
		if defaultStorage != nil && defaultStorage.Type == storepb.StorageType_STORAGE_TYPE_S3 {
			s3Config := defaultStorage.GetS3Config()
			if s3Config == nil {
				return errors.New("storageSetting default storage S3 config is required")
			}
			for _, field := range []struct {
				name  string

View on GitHub (pinned to 14d757ce1f)

Solutions

1. Add a "storageSetting" object: { "key": "STORAGE", "storageSetting": { "storageType": "LOCAL", "uploadSizeLimitMb": 32 } }.
2. Check the exact lowerCamelCase key storageSetting.

Example fix

// before
{ "key": "STORAGE" }

// after
{ "key": "STORAGE", "storageSetting": { "storageType": "LOCAL", "uploadSizeLimitMb": 32 } }

if setting.Key == storepb.InstanceSettingKey_STORAGE && setting.GetStorageSetting() == nil {
    return errors.New("STORAGE setting requires a storageSetting payload")
}

func hasStoragePayload(s *storepb.InstanceSetting) bool {
    return s.GetKey() == storepb.InstanceSettingKey_STORAGE && s.GetStorageSetting() != nil
}

When it happens

Trigger: A memos-instance-setting-storage.json containing only { "key": "STORAGE" }, or with a mistyped payload key ("storage_setting", "storage") that protojson ignores so the oneof stays unset.

Common situations: Authoring a storage file that only lists S3 storages at the wrong nesting level; templating that renders an empty object; renaming keys when converting from the admin API JSON dump.

Related errors

• generalSetting must be populated for key GENERAL
• generalSetting.weekStartDayOffset must be between -1 and 6
• storageSetting.s3Config is required for S3
• storageSetting.uploadSizeLimitMb must not be negative
• storageSetting default storage S3 config is required

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