What causes "expected ',' or ']' in array, got %q" in vitessio/vitess?

Run json.Valid (or encoding/json Unmarshal) on the payload before writing; reject invalid documents at the boundary.

expected ',' or ']' in array, got %q

Error message

expected ',' or ']' in array, got %q

What it means

While serializing a JSON array into a JSON_ARRAY(...) SQL expression, the parser expects the next byte after an element to be a comma (element separator) or the closing bracket. If the byte at the current position is anything else, the array is structurally malformed and the writer aborts with this error, reporting the offending character. This prevents silently producing a wrong SQL expression from corrupted input.

Source

Thrown at go/mysql/json/marshal.go:323

	}
}

func (w *sqlWriter) writeArray(depth int) error {
	w.buf.WriteString("JSON_ARRAY(")
	first := true
	for {
		w.skipWhitespace()
		if w.pos >= len(w.data) {
			return errors.New("unexpected end of JSON input in array")
		}
		if w.data[w.pos] == ']' {
			w.pos++
			w.buf.WriteByte(')')
			return nil
		}
		if !first {
			if w.data[w.pos] != ',' {
				return fmt.Errorf("expected ',' or ']' in array, got %q", w.data[w.pos])
			}
			w.pos++
			w.buf.WriteString(", ")
		}
		first = false

		if err := w.writeValue(false, depth+1); err != nil {
			return err
		}
	}
}

func (w *sqlWriter) writeString(top bool) error {
	if top {
		w.buf.WriteString("CAST(JSON_QUOTE(")
	}
	w.buf.WriteString("_utf8mb4")
	if err := w.writeStringContent(); err != nil {

View on GitHub (pinned to 01a25a7d17)

Solutions

Run json.Valid (or encoding/json Unmarshal) on the payload before writing; reject invalid documents at the boundary.
Inspect the character reported in the error to find the missing/misplaced comma in the array and fix the producer that emitted it.
Replace hand-rolled JSON construction with json.Marshal / json.Encoder so separators and brackets are always correct.
If truncation is the cause, read the full document (e.g. length-prefixed framing) before parsing instead of parsing partial buffers.

Example fix

// before: elements concatenated without separators
s := "[" + strings.Join(items, " ") + "]"
// after
b, _ := json.Marshal(items)

Defensive patterns

Strategy: validation

Validate before calling

if !json.Valid(input) {
	return errors.New("payload is not valid JSON: array separator missing or misplaced")
}

Try / catch

if err := writeJSONAsSQL(input); err != nil {
	if strings.Contains(err.Error(), "expected ',' or ']' in array") {
		return reencodeWithStdLib(rawSource) // rebuild from original typed data
	}
	return err
}

Prevention

Serialize arrays with json.Marshal instead of joining strings
Never parse partially-read buffers; read the complete document first
Keep hand-written JSON fixtures covered by json.Valid tests
Reject non-standard serializations at ingestion time

When it happens

Trigger: Calling the JSON-to-SQL writer with an array containing adjacent values without a comma (e.g. [1 2]), a stray character between elements (e.g. [1 ; 2]), a missing closing bracket followed by unexpected bytes ([1 2]] with the inner document truncated), or an object used where the array separator was expected ([{}} malformed).

Common situations: JSON produced by concatenating serialized elements without separators in custom logging or batching code; truncated documents from network reads or fixed-size buffers; hand-written JSON fixtures with typos; data migrated from a system that emits a non-standard serialization.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/61943d9490a06369. Report an issue: GitHub.