What causes "opensearch: invalid index config" in Tencent/WeKnora?

Identify the node type printed in the error (%T) and rewrite the query to use only supported expression constructs (standard operators, casts, functions on the allowlist).

Tencent/WeKnora · error · AppError

opensearch: invalid index config

Error message

opensearch: invalid index config

What it means

The recursive expression validator uses default-deny: after checking every recognized node type, any Node variant not in its safe allowlist (operators, casts, column refs, constants, etc.) hits the default branch and is rejected with the concrete Go type name. This ensures unknown or newly added PG17 node types can never bypass validation.

Source

Thrown at internal/application/repository/retriever/opensearch/errors.go:37

	// single batch disagree).
	ErrDimensionMismatch = errors.New("opensearch: embedding dimension mismatch")

	// ErrAuth — cluster returned 401 / 403. Distinguished from ErrTransport
	// so the service layer can map to a clean 4xx instead of 503.
	ErrAuth = errors.New("opensearch: authentication failed")

	// ErrTransport — network / 5xx / opaque cluster error. Classified as
	// transient: ensureReady does NOT persist this in initErr, so the next
	// caller will retry.
	ErrTransport = errors.New("opensearch: transport error")

	// ErrVersionUnsupported — cluster is not OpenSearch, is OS 1.x, or is
	// OS 2.0~2.3 (pre-Lucene-HNSW-GA). probeVersion enforces.
	ErrVersionUnsupported = errors.New("opensearch: cluster version unsupported")

	// ErrConfigInvalid — IndexConfig / storeID / sanitizeIndexName guard
	// failed, or the k-NN plugin is missing on one or more cluster nodes.
	ErrConfigInvalid = errors.New("opensearch: invalid index config")

	// ErrFeatureNotEnabled — stubs.go returns this from methods whose real
	// implementation has not landed yet (CopyIndices / BatchUpdateChunk* /
	// swapToVersion, plus the read/write methods that a follow-up commit
	// will replace with production code).
	ErrFeatureNotEnabled = errors.New("opensearch: feature not enabled in this build")

	// ErrBatchTooLarge — Save / Delete batch exceeded the driver's sync
	// cap. Distinct from ErrFeatureNotEnabled so the service layer can
	// chunk + retry rather than treat the failure as "waiting on a future
	// implementation."
	ErrBatchTooLarge = errors.New("opensearch: batch size exceeds driver cap")

	// ErrCircuitBreaker — OpenSearch k-NN circuit breaker returned 429
	// (knn_circuit_breaker_exception). Classified as transient so the
	// caller can retry after the operator scales the cluster.
	ErrCircuitBreaker = errors.New("opensearch: knn circuit breaker open")
)

View on GitHub (pinned to 988cbb0330)

Solutions

Identify the node type printed in the error (%T) and rewrite the query to use only supported expression constructs (standard operators, casts, functions on the allowlist).
If the node type is a known-safe new PG17 node, add it to the type switch with proper recursive validation of its children — never as an unconditional allow.
If the error appeared after a pg_query_go upgrade, pin the previous version or patch the validator's allowlist for the new node types.

Example fix

// before
SELECT JSON_TABLE(...); -- produces unrecognized JsonExpr node

// after
SELECT jsonb_extract_path_text(doc, 'a', 'b') FROM reports; -- FuncCall path is validated

Defensive patterns

Strategy: try-catch

Validate before calling

func usesUnsupportedSyntax(sql string) error {
	// surface a friendly message before hitting the default-deny branch
	for _, pat := range []string{`(?i)\bjson_table\s*\(`, `(?i)\bjson\s*\(`} {
		if regexp.MustCompile(pat).MatchString(sql) {
			return fmt.Errorf("SQL/JSON query syntax is not supported")
		}
	}
	return nil
}

Try / catch

if err := validator.ValidateQuery(sql); err != nil {
	var t unsupportedNodeType
	if errors.As(err, &t) {
		log.Warnf("validator rejected node %s; consider allowlisting if safe", t)
		return fmt.Errorf("query uses unsupported expression syntax: %w", err)
	}
}

Prevention

After upgrading pg_query_go, run the test suite for new default-deny rejections.
Restrict queries to well-known expression constructs (operators, casts, allowlisted functions, literals).
When adding a node to the allowlist, always recurse into its children — never allow it blind.

When it happens

Trigger: Validating a query using an expression node type outside the allowlist — e.g. newer PG17 SQL/JSON constructs (JsonExpr, JsonConstructorExpr), MergeSupportFunc, or any node type added by a pg_query_go version upgrade before the validator was updated.

Common situations: Upgrading the pg_query_go protobuf library to a PostgreSQL version with new expression node types; using SQL/JSON query functions (JSON_TABLE, JSON()) that produce novel nodes; queries with exotic syntax the allowlist never anticipated.

Related errors

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/6698366f5a3b8f92. Report an issue: GitHub.