kopia/kopia · error

invalid format

Error message

invalid format

What it means

Thrown by webhook Options.ApplyDefaultsAndValidate when sender.ValidateMessageFormatAndSetDefault rejects the configured message format. The format must be one of the sender package's supported values; anything else is rejected.

Solutions

1. Omit the `format` field to get the default (text/plain).
2. Set `format` to a supported value such as "text/plain" (see sender.FormatPlainText and siblings).
3. Check sender.ValidateMessageFormatAndSetDefault for the exact list of accepted formats.
4. Fix the casing—format values are compared exactly.

Example fix

// before
{"format": "xml"}
// after
{"format": "text/plain"}

switch opts.Format {
case "", sender.FormatPlainText /* plus other supported formats */ :
    // ok
default:
    return fmt.Errorf("unsupported format %q", opts.Format)
}

if err := opts.ApplyDefaultsAndValidate(ctx); err != nil {
    if strings.Contains(err.Error(), "invalid format") {
        return fmt.Errorf("use a supported format, e.g. %q", sender.FormatPlainText)
    }
    return err
}

When it happens

Trigger: Creating or updating webhook notification config with `format` set to an unsupported string (e.g. "xml", "rich-text", case variants like "HTML").

Common situations: Typo or wrong assumption about supported formats in the notification profile config; copying config from another tool with different format names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid notification configuration
• error preparing notification
• invalid endpoint
• invalid endpoint scheme, must be http:// or https://
• invalid --http-header

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/16c940e373ab6c14. Report an issue: GitHub.

Appendix: source

Thrown at notification/sender/webhook/webhook_sender_options.go:27

	"github.com/kopia/kopia/notification/sender"
)

// Options defines Webhook sender options.
type Options struct {
	Endpoint string `json:"endpoint"`
	Method   string `json:"method"`
	Format   string `json:"format"`
	Headers  string `json:"headers"` // newline-separated list of headers (key: value)
}

// ApplyDefaultsAndValidate applies default values and validates the configuration.
func (o *Options) ApplyDefaultsAndValidate(_ context.Context) error {
	if o.Method == "" {
		o.Method = "POST"
	}

	if err := sender.ValidateMessageFormatAndSetDefault(&o.Format, sender.FormatPlainText); err != nil {
		return errors.Wrap(err, "invalid format")
	}

	u, err := url.ParseRequestURI(o.Endpoint)
	if err != nil {
		return errors.Errorf("invalid endpoint")
	}

	if u.Scheme != "http" && u.Scheme != "https" {
		return errors.Errorf("invalid endpoint scheme, must be http:// or https://")
	}

	if o.Format == "" {
		o.Format = sender.FormatPlainText
	}

	return nil
}

View on GitHub (pinned to 82495e54b5)