VictoriaMetrics/VictoriaMetrics · error

missing `put ` prefix in %q

Error message

missing `put ` prefix in %q

What it means

The OpenTSDB parser (lib/protoparser/opentsdb) expects each line of a telnet-style put request to start with the literal prefix 'put '. Row.unmarshal returns this error when a line does not. It is a line-format validation error for the OpenTSDB text protocol.

Source

Thrown at lib/protoparser/opentsdb/parser.go:62

type Row struct {
	Metric    string
	Tags      []Tag
	Value     float64
	Timestamp int64
}

func (r *Row) reset() {
	r.Metric = ""
	r.Tags = nil
	r.Value = 0
	r.Timestamp = 0
}

func (r *Row) unmarshal(s string, tagsPool []Tag) ([]Tag, error) {
	r.reset()
	s = trimLeadingSpaces(s)
	if !strings.HasPrefix(s, "put ") {
		return tagsPool, fmt.Errorf("missing `put ` prefix in %q", s)
	}
	s = s[len("put "):]
	s = trimLeadingSpaces(s)
	n := strings.IndexByte(s, ' ')
	if n < 0 {
		return tagsPool, fmt.Errorf("cannot find whitespace between metric and timestamp in %q", s)
	}
	r.Metric = s[:n]
	if len(r.Metric) == 0 {
		return tagsPool, fmt.Errorf("metric cannot be empty")
	}
	tail := trimLeadingSpaces(s[n+1:])
	n = strings.IndexByte(tail, ' ')
	if n < 0 {
		return tagsPool, fmt.Errorf("cannot find whitespace between timestamp and value in %q", s)
	}
	timestamp, err := fastfloat.Parse(tail[:n])
	if err != nil {

View on GitHub (pinned to 5079fb58f1)

Solutions

1. Prefix each line with 'put ' followed by metric timestamp value tag=k=v pairs.
2. Verify you are not sending extra leading content; note trimLeadingSpaces strips spaces but the 'put ' keyword itself is required.
3. Use the OpenTSDB JSON API endpoint instead if your payload is JSON.
4. Test one line with curl against the OpenTSDB insert endpoint before batching.

Example fix

// before
"sys.cpu.user 1496412345 42 host=web01"
// after
"put sys.cpu.user 1496412345 42 host=web01"

// validate line before sending to OpenTSDB telnet-style endpoint
re := regexp.MustCompile(`^put \S+ \d+ \S+`)
if !re.MatchString(line) {
    return fmt.Errorf("invalid opentsdb line: %q", line)
}

if err := parser.Parse(body, cb); err != nil {
    if strings.Contains(err.Error(), "missing `put ` prefix") {
        // offending line is quoted in the error; fix its format
    }
}

When it happens

Trigger: POSTing lines to the OpenTSDB API insert handler that lack the leading 'put ' keyword, e.g. 'sys.cpu.user 1234567890 1 host=web01' without the prefix.

Common situations: Scripts written against a different text format; missing prefix after naive trimming of whitespace; sending OpenTSDB JSON API payloads to the telnet-style endpoint.

Related errors

• cannot find whitespace between metric and timestamp in %q
• metric cannot be empty
• cannot find whitespace between timestamp and value in %q
• missing `metric` in %s
• missing `value` in %s

AI-assisted analysis of VictoriaMetrics/VictoriaMetrics@5079fb58f1 (2026-09-03). Data as JSON: /api/errors/bd5a2e9effeecf89. Report an issue: GitHub.