googleapis/mcp-toolbox · error

unable to execute query: %w

Error message

unable to execute query: %w

What it means

Wraps any failure from falkordb-go's graph.Query or graph.ROQuery when executing a Cypher statement. Because execution is delegated to the driver, this covers syntax errors, runtime graph errors, timeouts, and connection failures — all normalized into one wrapper by RunQuery.

Source

Thrown at internal/sources/falkordb/falkordb.go:195

			return nil, fmt.Errorf("unable to explain query: %w", err)
		}
		return map[string]any{"plan": plan}, nil
	}

	var opts *falkordb.QueryOptions
	if s.QueryTimeoutMs > 0 {
		opts = falkordb.NewQueryOptions().SetTimeout(s.QueryTimeoutMs)
	}

	var results *falkordb.QueryResult
	var err error
	if readOnly {
		results, err = graph.ROQuery(cypherStr, params, opts)
	} else {
		results, err = graph.Query(cypherStr, params, opts)
	}
	if err != nil {
		return nil, fmt.Errorf("unable to execute query: %w", err)
	}

	out := convertRecords(results)
	if len(out) == 0 {
		if stats := mutationStats(results); len(stats) > 0 {
			return map[string]any{"stats": stats}, nil
		}
	}
	return out, nil
}

// convertRecords converts a query result set into JSON-compatible rows.
func convertRecords(results *falkordb.QueryResult) []map[string]any {
	var out []map[string]any
	for results.Next() {
		record := results.Record()
		vMap := make(map[string]any)
		keys := record.Keys()

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Run the Cypher directly in FalkorDB browser/cli to see the raw server error
2. Check readOnly flag: write queries must go through Query, not ROQuery
3. Validate Cypher syntax and parameter names/values match the declared parameters
4. Increase QueryTimeoutMs or check server-side query timeout settings

Example fix

// before
results, err = graph.ROQuery(cypherStr, params, opts)
// after
if readOnly {
    results, err = graph.ROQuery(cypherStr, params, opts)
} else {
    results, err = graph.Query(cypherStr, params, opts)
}
if err != nil {
    return nil, fmt.Errorf("unable to execute query (readonly=%v): %w", readOnly, err)
}

// Pre-validate Cypher cheaply if supported
if strings.TrimSpace(cypherStr) == "" { return errors.New("empty cypher query") }
if readOnly && isWriteCypher(cypherStr) { return errors.New("write statement in read-only query") }

func isTimeoutErr(err error) bool {
    return errors.Is(err, context.DeadlineExceeded) || strings.Contains(err.Error(), "timeout")
}

results, err := graph.Query(cypherStr, params, opts)
if err != nil {
    if isTimeoutErr(err) {
        // retry once with a larger timeout
    } else if strings.Contains(err.Error(), "Syntax error") {
        // do not retry; surface to caller for correction
    }
    return nil, fmt.Errorf("unable to execute query: %w", err)
}

When it happens

Trigger: RunQuery called (readOnly selects ROQuery vs Query) and the Cypher string fails to parse, references a missing graph/label/procedure, exceeds QueryTimeoutMs, or the connection drops mid-execution.

Common situations: Invalid Cypher syntax; calling a write via ROQuery and getting a read-only rejection; parameter type mismatches in params map; query timeout configured too low; graph deleted between calls.

Related errors

• unable to execute query: %w
• unable to execute query: %w
• this tool is read-only and cannot execute write queries
• unable to execute client: %w
• errors encountered by results.Scan: %w

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