kopia/kopia · error

invalid --http-header

Error message

invalid --http-header %q, must be key:value

What it means

Input validation in the webhook notification configure command: each --http-header value must contain exactly one ':' separating key and value, enforced by splitting with strings.SplitN(h, ":", 2) and requiring 2 parts. Values without a colon are rejected with this errors.Errorf before any profile is touched.

Solutions

1. Always provide the header as key:value, e.g. --http-header "Authorization: Bearer TOKEN"
2. Quote the argument in the shell so spaces and colons survive parsing
3. Note only the FIRST colon separates key from value; colons in the value are fine

Example fix

// before
--http-header Authorization
// after
--http-header "Authorization: Bearer eyJ..."

func validHeader(h string) bool {
    return strings.Contains(h, ":") && len(strings.SplitN(h, ":", 2)) == 2 && strings.SplitN(h, ":", 2)[0] != ""
}
// reject invalid headers before invoking kopia
for _, h := range headers {
    if !validHeader(h) { return fmt.Errorf("invalid --http-header %q", h) }
}

if err := configureWebhook(ctx); err != nil && strings.Contains(err.Error(), "invalid --http-header") {
    // re-run with corrected key:value arguments
}

When it happens

Trigger: Passing `--http-header` values with no colon at all (e.g. `Authorization` instead of `Authorization: Bearer xyz`); kopia splits on ':' and gets fewer than 2 parts.

Common situations: Forgetting the value; passing a header name only; shell quoting mistakes that drop the ':'-containing part.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• invalid format
• invalid notification configuration
• action script file ( ) too long: , max allowed
• Cannot specify a 'point-in-time' option when creating a…
• Cannot specify a 'point-in-time' option when creating a…

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

Appendix: source

Thrown at cli/command_notification_configure_webhook.go:40

	c.common.setup(svc, cmd)

	var httpHeaders []string

	cmd.Flag("endpoint", "SMTP server").StringVar(&c.opt.Endpoint)
	cmd.Flag("method", "HTTP Method").EnumVar(&c.opt.Method, http.MethodPost, http.MethodPut)
	cmd.Flag("http-header", "HTTP Header (key:value)").StringsVar(&httpHeaders)
	cmd.Flag("format", "Format of the message").EnumVar(&c.opt.Format, sender.FormatHTML, sender.FormatPlainText)

	act := configureNotificationAction(svc, &c.common, webhook.ProviderType, &c.opt, webhook.MergeOptions)

	cmd.Action(func(ctx *kingpin.ParseContext) error {
		for _, h := range httpHeaders {
			const numParts = 2

			parts := strings.SplitN(h, ":", numParts)
			if len(parts) != numParts {
				return errors.Errorf("invalid --http-header %q, must be key:value", h)
			}
		}

		c.opt.Headers = strings.Join(httpHeaders, "\n")

		return act(ctx)
	})
}

View on GitHub (pinned to 82495e54b5)