googleapis/mcp-toolbox · error

unable to execute query: %w

Error message

unable to execute query: %w

What it means

Returned by Source.RunSQL when the Couchbase N1QL query (scope.Query) call itself fails. The library wraps the gocb error as 'unable to execute query: %w'. This covers query-submission failures: malformed N1QL syntax, missing index, bucket/scope errors, authentication, or network failures — not row decoding.

Source

Thrown at internal/sources/couchbase/couchbase.go:125

func (s *Source) ToConfig() sources.SourceConfig {
	return s.Config
}

func (s *Source) CouchbaseScope() *gocb.Scope {
	return s.Scope
}

func (s *Source) CouchbaseQueryScanConsistency() uint {
	return s.QueryScanConsistency
}

func (s *Source) RunSQL(statement string, params parameters.ParamValues) (any, error) {
	results, err := s.CouchbaseScope().Query(statement, &gocb.QueryOptions{
		ScanConsistency: gocb.QueryScanConsistency(s.CouchbaseQueryScanConsistency()),
		NamedParameters: params.AsMap(),
	})
	if err != nil {
		return nil, fmt.Errorf("unable to execute query: %w", err)
	}

	out := []any{}
	for results.Next() {
		var result json.RawMessage
		err := results.Row(&result)
		if err != nil {
			return nil, fmt.Errorf("error processing row: %w", err)
		}
		out = append(out, result)
	}
	return out, nil
}

func (r Config) createCouchbaseOptions() (gocb.ClusterOptions, error) {
	cbOpts := gocb.ClusterOptions{}

	if r.Username != "" {

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Run the statement in the Couchbase web console Query tab to see the raw N1QL error
2. Create missing indexes: CREATE PRIMARY INDEX ON `bucket`.`scope`.`collection` if 'no index available' appears
3. Verify N1QL syntax — Couchbase is not ANSI SQL; adjust unsupported clauses
4. Check the user's RBAC roles (Query Select etc.) and cluster connectivity/scan-consistency config

Example fix

// before (RunSQL statement)
SELECT * FROM users WHERE age > 21;
// fails without an index
// after
CREATE PRIMARY INDEX ON `travel-sample`.inventory.users;
SELECT * FROM `travel-sample`.inventory.users WHERE age > 21;

// Validate statement and index existence before running
// 1. Sanity-check N1QL syntax in the Couchbase console.
// 2. Programmatically verify a primary index exists:
q := "SELECT COUNT(*) AS idx FROM system:indexes WHERE keyspace_id = 'users' AND state = 'online'"
// run via the same SDK; if 0, run:
// CREATE PRIMARY INDEX ON `bucket`.`scope`.`users`

results, err := scope.Query(statement, opts)
if err != nil {
	var qErr *gocb.QueryError
	if errors.As(err, &qErr) {
		if strings.Contains(qErr.Error(), "No index available") {
			// create primary index or add a secondary index, then retry
		}
		if strings.Contains(qErr.Error(), "syntax error") {
			// surface statement to the user; N1QL != ANSI SQL
		}
	}
	return nil, fmt.Errorf("unable to execute query: %w", err)
}

When it happens

Trigger: Calling RunSQL with a statement that fails at the query service: syntax error in N1QL, nonexistent keyspace/scope, missing primary/secondary index, invalid named parameters, query service unreachable, or credentials lacking query privileges.

Common situations: SQL-habit syntax not valid in N1QL, missing primary index on the bucket (common new-bucket mistake), wrong scan consistency setting value, Couchbase connection config pointing at wrong cluster, RBAC role missing for the user.

Related errors

• error processing row: %w
• tool execution failed: %w
• toolbox failed to initialize: %w
• unable to create pool: %w
• unable to parse rows: %w

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/b2f4656ec167fcb9. Report an issue: GitHub.