{"record":{"id":"bf90a937744dd5be","repo":"googleapis/mcp-toolbox","slug":"unable-to-explain-query-w","errorCode":null,"errorMessage":"unable to explain query: %w","messagePattern":"unable to explain query: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/falkordb/falkordb.go","lineNumber":177,"sourceCode":"}\n\n// RunQuery executes a Cypher query against a graph in the FalkorDB instance.\n// An empty graphName targets the source's default graph. readOnly queries are\n// dispatched as GRAPH.RO_QUERY, so the server itself rejects write operations.\n// dryRun returns the GRAPH.EXPLAIN execution plan without running the query.\nfunc (s *Source) RunQuery(ctx context.Context, graphName, cypherStr string, params map[string]any, readOnly, dryRun bool) (any, error) {\n\tif graphName == \"\" {\n\t\tgraphName = s.Graph\n\t}\n\tgraph := s.Client.SelectGraph(graphName)\n\n\tif dryRun {\n\t\t// GRAPH.EXPLAIN replies with an array of plan lines, which\n\t\t// falkordb-go's ExecutionPlan does not handle; issue the command\n\t\t// directly instead.\n\t\tplan, err := s.Client.Conn.Do(ctx, \"GRAPH.EXPLAIN\", graphName, cypherStr).StringSlice()\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"unable to explain query: %w\", err)\n\t\t}\n\t\treturn map[string]any{\"plan\": plan}, nil\n\t}\n\n\tvar opts *falkordb.QueryOptions\n\tif s.QueryTimeoutMs > 0 {\n\t\topts = falkordb.NewQueryOptions().SetTimeout(s.QueryTimeoutMs)\n\t}\n\n\tvar results *falkordb.QueryResult\n\tvar err error\n\tif readOnly {\n\t\tresults, err = graph.ROQuery(cypherStr, params, opts)\n\t} else {\n\t\tresults, err = graph.Query(cypherStr, params, opts)\n\t}\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to execute query: %w\", err)","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/falkordb/falkordb.go#L159-L195","documentation":"This error wraps the underlying Redis-protocol failure returned when issuing a raw GRAPH.EXPLAIN command to a FalkorDB server during a dry-run query. The source bypasses falkordb-go's ExecutionPlan parser (which cannot handle the raw array of plan lines) by calling s.Client.Conn.Do directly, so any transport, auth, or server-side command error surfaces here.","triggerScenarios":"RunQuery invoked with dryRun=true while the GRAPH.EXPLAIN command fails: server unreachable, connection closed, wrong graph name, unsupported/renamed GRAPH.EXPLAIN command on older RedisGraph versions, or a non-string reply type that StringSlice() cannot decode.","commonSituations":"Container/network misconfig pointing at the wrong port; FalkorDB module not loaded so GRAPH.EXPLAIN returns unknown-command; typo in graphName; TLS/auth mismatch; running against plain Redis without the graph module.","solutions":["Verify the FalkorDB server is reachable and the graph module is loaded (run GRAPH.QUERY or PING first)","Check graphName exists (GRAPH.LIST) and the Cypher string is non-empty","Upgrade FalkorDB/RedisGraph to a version that supports GRAPH.EXPLAIN","Inspect the wrapped error with errors.Unwrap/log %v for the concrete redis failure (auth, timeout, decode)"],"exampleFix":"// before\nplan, err := s.Client.Conn.Do(ctx, \"GRAPH.EXPLAIN\", graphName, cypherStr).StringSlice()\nif err != nil {\n    return nil, fmt.Errorf(\"unable to explain query: %w\", err)\n}\n// after\nplan, err := s.Client.Conn.Do(ctx, \"GRAPH.EXPLAIN\", graphName, cypherStr).StringSlice()\nif err != nil {\n    return nil, fmt.Errorf(\"unable to explain query (graph=%s): %w\", graphName, err)\n}","handlingStrategy":"try-catch","validationCode":"// Before dryRun, check module availability\nres := client.Do(ctx, \"COMMAND\", \"INFO\")\nif err := res.Err(); err != nil { return err }\n// or verify graph exists\nexists, _ := client.Do(ctx, \"GRAPH.LIST\").StringSlice()","typeGuard":"func isRedisError(err error) bool {\n    var rErr *redis.Error\n    return errors.As(err, &rErr)\n}","tryCatchPattern":"plan, err := s.Client.Conn.Do(ctx, \"GRAPH.EXPLAIN\", graph, cypher).StringSlice()\nif err != nil {\n    var rErr redis.Error\n    if errors.As(err, &rErr) && strings.Contains(err.Error(), \"unknown command\") {\n        // fall back: run query with timeout 0 or surface module-missing guidance\n    }\n    return nil, fmt.Errorf(\"dry-run explain failed: %w\", err)\n}","preventionTips":["Confirm FalkorDB module is loaded before enabling dry-run tooling","Keep client library and server versions compatible (GRAPH.EXPLAIN reply shape changed across versions)","Include graph name in wrapped errors for faster triage","Smoke-test GRAPH.EXPLAIN in CI against the same server image used in production"],"tags":["falkordb","graph-database","dry-run","redis-protocol"],"backgroundTag":"graph-explain-command-failed","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}