Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Show readable paths in Metabot's query validation errors (#84814)

Andrei Simionescuf140385e7179
diff --git a/src/metabase/agent_lib/representations.clj b/src/metabase/agent_lib/representations.clj
index e3ca85b32f0..b0055913fa4 100644
--- a/src/metabase/agent_lib/representations.clj
+++ b/src/metabase/agent_lib/representations.clj
@@ -25,6 +25,7 @@
`fields`;
* explicit joins supported; implicit joins are filled in by the repair pass."
(:require
+ [clojure.string :as str]
[malli.core :as mc]
[malli.transform :as mtx]
[metabase.lib.schema :as lib.schema]
@@ -240,3 +241,45 @@
:schema ::query
:response/keys #{:humanized :details}})))
parsed)
+
+(defn query-path
+ "Format a query location as a dotted path with bracketed indices, or `(root)` for an empty path."
+ [path]
+ (if (seq path)
+ (reduce (fn [s part]
+ (if (integer? part)
+ (str s "[" part "]")
+ (str s (when (seq s) ".") (if (keyword? part) (keyword->repr-string part) part))))
+ "" path)
+ "(root)"))
+
+(defn- humanized-locations
+ [path errors]
+ (cond
+ (nil? errors) nil
+ (map? errors) (mapcat (fn [[k v]] (humanized-locations (conj path k) v)) errors)
+ (seq? errors) (mapcat #(humanized-locations path %) errors)
+ (vector? errors)
+ (mapcat (fn [[i v]] (humanized-locations (conj path i) v)) (map-indexed vector errors))
+ :else [[path (str errors)]]))
+
+(def ^:private max-humanized-paths-length
+ "Character budget for structural validation paths, including the truncation marker."
+ 500)
+
+(defn humanized->paths
+ "Flatten humanized validation errors into readable paths, capped at [[max-humanized-paths-length]] with an ellipsis."
+ [humanized]
+ (let [locations (humanized-locations [] humanized)
+ by-path (group-by first locations)
+ text (->> (distinct (map first locations))
+ (map (fn [path]
+ (str (query-path path) ": "
+ (str/join ", " (distinct (map second (get by-path path)))))))
+ (interpose "; ")
+ (mapcat seq)
+ (take (inc max-humanized-paths-length))
+ (apply str))]
+ (if (> (count text) max-humanized-paths-length)
+ (str (subs text 0 (dec max-humanized-paths-length)) "\u2026")
+ text)))
diff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.clj
index f97428b6f6b..61ebcdc0546 100644
--- a/src/metabase/metabot/tools/construct.clj
+++ b/src/metabase/metabot/tools/construct.clj
@@ -712,7 +712,8 @@
(when-let [explanation (mr/explain :metabase.lib.schema/query pmbql-query)]
(let [errors (sort-by (comp nil? not-runnable-problem) (:errors explanation))]
(cond-> (or (some->> errors
- (map #(str (pr-str (:in %)) ": " (or (not-runnable-problem %) (me/error-message %))))
+ (map #(str (repr/query-path (:in %)) ": "
+ (or (not-runnable-problem %) (me/error-message %))))
distinct
(take 3)
seq
@@ -822,11 +823,9 @@
shape and concentrates on the LLM-friendly repair passes.
Pipeline:
- 1. Boundary-validate the keyword-keyed input against `::lib.schema/external-query`
- ([[repr/validate-external-query]]). Catches structural issues — missing `stages`,
- typo'd stage keys (e.g. `aggreagation` vs `aggregation`), wrong top-level `lib/type`,
- etc. — that the loose `:map` wire schema doesn't catch.
- 2. Convert to the string-keyed portable form the repair pipeline operates on.
+ 1. Convert to the string-keyed portable form the repair pipeline operates on.
+ 2. Reject unknown stage keys, such as `aggreagation` for `aggregation`
+ ([[repr/assert-known-stage-keys!]]).
3. Resolve the database id from the first stage's `source-table:` / `source-card:`
([[resolve-database-id-from-first-stage]]) and build an application-DB-backed
`MetadataProvider`.
@@ -889,7 +888,7 @@
_validated (repr/validate-query repaired)
pmbql-query (repr.resolve/resolve-query mp repaired permission-aware-content-store)
_runnable (when-let [why (query-not-runnable-explanation pmbql-query)]
- (throw (ex-info (tru "The constructed query is not runnable - it would fail the query builder''s validation, so it cannot be visualized or saved. Problem in {0}."
+ (throw (ex-info (tru "The constructed query is not runnable - it would fail the query builder''s validation, so it cannot be visualized or saved. Failing paths: {0}."
why)
{:agent-error? true
:error :query-not-runnable
@@ -911,7 +910,11 @@
:usable-sources usable-sources
:status-code 400}))))
exported-repr (repr.resolve/export-query mp pmbql-query permission-aware-content-store)
- _validated' (repr/validate-query exported-repr)
+ _validated' (try
+ (repr/validate-query exported-repr)
+ (catch clojure.lang.ExceptionInfo e
+ (throw (IllegalStateException.
+ "Exported representations query has an invalid structure." e))))
query-id (u/generate-nano-id)]
{:structured-output {:query-id query-id
:query pmbql-query
diff --git a/src/metabase/metabot/tools/core.clj b/src/metabase/metabot/tools/core.clj
index a24a88a5e90..41d0cf6366e 100644
--- a/src/metabase/metabot/tools/core.clj
+++ b/src/metabase/metabot/tools/core.clj
@@ -33,6 +33,7 @@
follow one tool's behaviour without knowing which other shapes exist."
(:require
[clojure.string :as str]
+ [metabase.agent-lib.representations :as repr]
[metabase.metabot.metadata-perms :as metabot.perms]
[metabase.metabot.schema.v2 :as schema.v2]
[metabase.metabot.tools.error :as tools.error]
@@ -470,7 +471,8 @@
(try
(thunk)
(catch Throwable e
- (let [{:keys [agent-error? status-code error entity-type entity-id source-card source-card-type]} (ex-data e)
+ (let [{:keys [agent-error? status-code error entity-type entity-id humanized
+ source-card source-card-type]} (ex-data e)
code (pipeline-error-code error)]
(cond
;; Lib exceptions can also carry `:agent-error?`, but their messages aren't written for the model.
@@ -478,6 +480,7 @@
(tools.error/throw-recoverable!
code
(cond-> {:message (or (ex-message e) "")}
+ (some? humanized) (assoc :paths (repr/humanized->paths humanized))
entity-type (assoc :entity-type entity-type)
(some? entity-id) (assoc :entity-id entity-id)
source-card (assoc :source-card source-card
diff --git a/src/metabase/metabot/tools/recoverable/pipeline.clj b/src/metabase/metabot/tools/recoverable/pipeline.clj
index 491d18efac1..86cef63ad58 100644
--- a/src/metabase/metabot/tools/recoverable/pipeline.clj
+++ b/src/metabase/metabot/tools/recoverable/pipeline.clj
@@ -9,9 +9,8 @@
`metabase://` URIs, portable FKs, `portable_entity_id` — and `tools.core/with-pipeline-errors`
converts a pipeline exception into the matching declaration.
- The pipeline's own message is authored text (it is built with `tru` and already reaches the model
- today), so it is the one foreign message a payload here may carry. Everything else about the
- exception stays in the logs.
+ The pipeline's own message, flattened validation paths, and entity references are the foreign
+ text a payload here may carry. Everything else about the exception stays in the logs.
A code with no declaration is not converted and becomes unrecoverable, which is why
`metabase.metabot.tools.recoverable.pipeline-test` scans the pipeline sources and fails when a
@@ -28,12 +27,14 @@
(mr/def ::payload
"The payload every pipeline-error declaration takes.
- `:message` is the pipeline's own sentence. `:entity-type` and `:entity-id` are present only for
- the codes whose recovery depends on what was referenced (see [[uri-in-source-table!]]).
+ `:message` is the pipeline's own sentence. `:paths` is the flattened structural validation text
+ the model reads. `:entity-type` and `:entity-id` are present only for the codes whose recovery
+ depends on what was referenced (see [[uri-in-source-table!]]).
`:source-card` and `:source-card-type` are the numeric ID and type of the stage's `source-card:`,
present only for the codes a `source-card:` stage raises (see [[column-not-returned!]])."
[:map {:closed true}
[:message :string]
+ [:paths {:optional true} :string]
[:entity-type {:optional true} [:maybe :string]]
[:entity-id {:optional true} [:maybe [:or :string :int]]]
[:source-card {:optional true} [:maybe :int]]
@@ -282,9 +283,17 @@
"A stage carried a key the representations format does not define."
[])
-(defpipeline-error invalid-representations-query!
+(defn- structural-recovery
+ [{:keys [paths]}]
+ (if (seq paths)
+ [{:uses #{} :text (str "Invalid at " paths ". Fix the named paths.")}]
+ []))
+
+(defrecoverable invalid-representations-query!
"The query did not parse as a representations query."
- [])
+ {:payload ::payload}
+ [payload]
+ {:message (:message payload), :recovery (structural-recovery payload)})
(defpipeline-error invalid-external-query!
"A query supplied from outside the pipeline was not a valid MBQL query."
diff --git a/src/metabase/metabot/tools/recovery_hints.clj b/src/metabase/metabot/tools/recovery_hints.clj
index 796ce58c808..39f227e7936 100644
--- a/src/metabase/metabot/tools/recovery_hints.clj
+++ b/src/metabase/metabot/tools/recovery_hints.clj
@@ -12,6 +12,7 @@
which is the intended failure mode: a missing hint reads as terse, a wrong one sends the
agent at a tool it does not have."
(:require
+ [metabase.agent-lib.representations :as repr]
[metabase.util.i18n :refer [tru]]))
(set! *warn-on-reflection* true)
@@ -43,10 +44,20 @@
(str "Call `read_resource` with `metabase://" source-card-type "/" source-card "/fields` to list the " what
" this " source-card-type " returns.")))
+(defn- structural-validation-hint
+ "Describe the failing paths in a humanized structural explanation, or nil when it has no errors."
+ [humanized]
+ (let [paths (repr/humanized->paths humanized)]
+ (when (seq paths)
+ (tru "Invalid at {0}. Fix the named paths." paths))))
+
(defn recovery-hint
"The v1 recovery sentence for an agent error's `ex-data`, or nil when it has none."
- [{:keys [error entity-type entity-id] :as data}]
+ [{:keys [error entity-type entity-id humanized] :as data}]
(case error
+ :invalid-representations-query
+ (structural-validation-hint humanized)
+
:uri-in-source-table
(uri-hint entity-type entity-id)
diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.clj
index ef07ad937f1..3642dbdc06c 100644
--- a/test/metabase/agent_api/api_test.clj
+++ b/test/metabase/agent_api/api_test.clj
@@ -2165,3 +2165,14 @@
(is (not (contains? q :qp/source-card-id)))
(is (every? (fn [stage] (not (contains? stage :qp/stage-had-source-card))) (:stages q))
"internal keys are stripped from every stage"))))
+
+(deftest construct-query-structural-locations-test
+ (let [response (mt/user-http-request :rasta :post 400 "agent/v2/construct-query"
+ {:query (orders-query :filters [{:op ">"} {:op "<"}])})]
+ (is (= "invalid-representations-query" (:error response)))
+ (is (= (str "Representations query has an invalid structure.\n"
+ "Invalid at stages[0].filters[0]: should be a vector, "
+ "clause must be [operator-string, options-map, \u2026args]; "
+ "stages[0].filters[1]: should be a vector, "
+ "clause must be [operator-string, options-map, \u2026args]. Fix the named paths.")
+ (:message response)))))
diff --git a/test/metabase/agent_lib/representations_test.clj b/test/metabase/agent_lib/representations_test.clj
index df8889cf9c8..704ba0b782b 100644
--- a/test/metabase/agent_lib/representations_test.clj
+++ b/test/metabase/agent_lib/representations_test.clj
@@ -3,7 +3,9 @@
external↔portable conversion, and the post-repair portable-form sanity schema."
(:require
[clojure.test :refer [deftest is testing]]
- [metabase.agent-lib.representations :as repr]))
+ [metabase.agent-lib.representations :as repr]
+ [metabase.util.malli.humanize :as mu.humanize]
+ [metabase.util.malli.registry :as mr]))
(set! *warn-on-reflection* true)
@@ -157,3 +159,60 @@
(let [data (validate-query-error (join-query-with-lib-type nil))]
(is (= :invalid-representations-query (:error data)))
(is (= 400 (:status-code data))))))
+
+(deftest ^:parallel humanized-paths-test
+ (let [base-query {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]}]}
+ stage-query #(update-in base-query ["stages" 0] merge %)
+ problem "should be a vector, clause must be [operator-string, options-map, \u2026args]"
+ field ["field" {} ["Sample" "PUBLIC" "ORDERS" "TOTAL"]]
+ join-query (join-query-with-lib-type "mbql/join")]
+ (doseq [[query expected]
+ [[(stage-query {"filters" {"op" ">"}})
+ "stages[0].filters: invalid type"]
+ [(stage-query {"filters" [{"op" ">"}]})
+ (str "stages[0].filters[0]: " problem)]
+ [(stage-query {"filters" [{"op" ">"} {"op" "<"}]})
+ (str "stages[0].filters[0]: " problem "; stages[0].filters[1]: " problem)]
+ [(stage-query {"filters" [[">" {} field 1] {"op" "<"} {"op" "="}]})
+ (str "stages[0].filters[1]: " problem "; stages[0].filters[2]: " problem)]
+ [(update base-query "stages" conj {"lib/type" "mbql.stage/mbql" "filters" [{"op" ">"}]})
+ (str "stages[1].filters[0]: " problem)]
+ [(update (stage-query {"filters" [{"op" ">"}]}) "stages" conj
+ {"lib/type" "mbql.stage/mbql" "aggregation" [{"op" "sum"}]})
+ (str "stages[0].filters[0]: " problem "; stages[1].aggregation[0]: " problem)]
+ [(assoc-in join-query ["stages" 0 "joins" 0 "fields"] [{"x" 1}])
+ (str "stages[0].joins[0].fields: should be either \"all\" or \"none\"; "
+ "stages[0].joins[0].fields[0]: " problem)]
+ [(stage-query {"joins" ["P"]})
+ "stages[0].joins[0]: invalid type"]
+ [(-> join-query
+ (assoc-in ["stages" 0 "joins" 0 "stages"] [])
+ (assoc-in ["stages" 0 "joins" 0 "conditions"] [{"op" "="}]))
+ (str "stages[0].joins[0].stages: should have at least 1 elements; "
+ "stages[0].joins[0].conditions[0]: " problem)]]]
+ (testing (pr-str query)
+ (is (= expected (repr/humanized->paths (:humanized (validate-query-error query)))))))
+ (testing "a valid query produces no failing paths"
+ (is (= "" (repr/humanized->paths (:humanized (validate-query-error base-query))))))
+ (testing "errors on the whole query have an explicit location"
+ (is (= "(root): invalid type" (repr/humanized->paths (:humanized (validate-query-error nil)))))))
+ (testing "keyword keys retain their namespace"
+ (is (= "stages[0].lib/type: missing required key"
+ (repr/humanized->paths
+ (mu.humanize/humanize
+ (mr/explain [:map [:stages [:sequential [:map [:lib/type :string]]]]]
+ {:stages [{}]})))))))
+
+(deftest ^:parallel humanized-paths-length-test
+ (let [humanized (fn [message]
+ (mu.humanize/humanize
+ (mr/explain [:map ["filters" [:fn {:error/message message} (constantly false)]]]
+ {"filters" nil})))]
+ (testing "short explanations retain all their text"
+ (let [text (apply str (repeat 491 "x"))]
+ (is (= (str "filters: " text) (repr/humanized->paths (humanized text))))))
+ (testing "long explanations end with an ellipsis within the character budget"
+ (is (= (str "filters: " (apply str (repeat 490 "x")) "\u2026")
+ (repr/humanized->paths (humanized (apply str (repeat 1000 "x")))))))))
diff --git a/test/metabase/agent_lib/test_util.clj b/test/metabase/agent_lib/test_util.clj
new file mode 100644
index 00000000000..e75f70b5922
--- /dev/null
+++ b/test/metabase/agent_lib/test_util.clj
@@ -0,0 +1,17 @@
+(ns metabase.agent-lib.test-util
+ (:require
+ [metabase.agent-lib.representations :as repr]))
+
+(set! *warn-on-reflection* true)
+
+(defn structural-validation-error
+ "The error that [[repr/validate-query]] throws for a query whose `filters` is a map instead of a list."
+ []
+ (try
+ (repr/validate-query {"lib/type" "mbql/query"
+ "database" "Sample"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "filters" {"op" ">"}}]})
+ (catch clojure.lang.ExceptionInfo e
+ e)))
diff --git a/test/metabase/mcp/v2/queries_test.clj b/test/metabase/mcp/v2/queries_test.clj
index f0a70359622..a9f8a4c5901 100644
--- a/test/metabase/mcp/v2/queries_test.clj
+++ b/test/metabase/mcp/v2/queries_test.clj
@@ -2,6 +2,7 @@
(:require
[clojure.string :as str]
[clojure.test :refer :all]
+ [metabase.agent-lib.test-util :as agent-lib.tu]
[metabase.mcp.v2.common :as common]
[metabase.mcp.v2.message :as message]
[metabase.mcp.v2.queries :as v2.queries]
@@ -232,3 +233,9 @@
(message/render (v2.recovery-hints/recovery-hint
{:error error :source-card 12 :source-card-type "question"})))
(str error)))))
+
+(deftest ^:parallel structural-validation-schema-detail-test
+ (is (= (str "\"Representations query has an invalid structure.\" "
+ "Invalid at \"stages\": [0] \"filters\": \"invalid type\". "
+ "Fix the named paths, or call \"learn\" with \"query-dialect\" for the clause shapes.")
+ (ex-message (#'v2.queries/with-schema-detail (agent-lib.tu/structural-validation-error))))))
diff --git a/test/metabase/mcp/v2/tools/query_test.clj b/test/metabase/mcp/v2/tools/query_test.clj
index 309674e868b..801ee8ce81e 100644
--- a/test/metabase/mcp/v2/tools/query_test.clj
+++ b/test/metabase/mcp/v2/tools/query_test.clj
@@ -1141,7 +1141,7 @@
(mt/with-current-user (mt/user->id :rasta)
(is (str/includes? (error-text (call! (str (random-uuid))
{:query (assoc (numeric-orders-query {:limit 1}) :evil "x")}))
- ":evil"))))))
+ "Failing paths: evil: disallowed key"))))))
;; not ^:parallel: mt/with-model-cleanup on the shared query-handle table
(deftest query-shape-still-reaches-the-qp-test
diff --git a/test/metabase/metabot/tools/construct_representations_test.clj b/test/metabase/metabot/tools/construct_representations_test.clj
index 87b46597d17..a1adedc1fb3 100644
--- a/test/metabase/metabot/tools/construct_representations_test.clj
+++ b/test/metabase/metabot/tools/construct_representations_test.clj
@@ -13,6 +13,7 @@
[malli.core :as mc]
[medley.core :as m]
[metabase.agent-lib.representations.repair :as repr.repair]
+ [metabase.agent-lib.representations.resolve :as repr.resolve]
[metabase.api.common :as api]
[metabase.lib-be.core :as lib-be]
[metabase.lib.convert :as lib.convert]
@@ -256,6 +257,33 @@
:source-table ["Sample" "PUBLIC" "ORDERS"]
:fields [["field" {} ["Sample" "PUBLIC" "ORDERS" "ID"]]]}]})
+(deftest export-validation-failures-end-metabot-turn-test
+ (with-mp-and-stubs!
+ (fn []
+ (let [export-query (mt/original-fn #'repr.resolve/export-query)]
+ (mt/with-dynamic-fn-redefs [repr.resolve/export-query
+ (fn [& args]
+ (assoc-in (apply export-query args) ["stages" 0 "filters"] {"op" ">"}))]
+ (let [caught (try
+ (tools/with-pipeline-errors
+ (construct/execute-representations-query orders-id-query))
+ (catch Throwable e e))
+ entries (tools/entries [construct/construct-notebook-query-tool])
+ outcome (tools.runtime/invoke entries
+ {:profile-id :nlq :metabot nil
+ :user-scope #{"agent:notebook:create"}
+ :tool-names (set (keys entries))}
+ "construct_notebook_query"
+ {:query orders-id-query
+ :title "Order IDs" :description "IDs of orders."})]
+ (is (nil? (:error (ex-data caught))))
+ (is (= :unrecoverable (:class (tools.error/classify caught))))
+ (is (= {:output "This call failed and the user was shown the error (:internal). Don't retry it."
+ :error {:class :unrecoverable :code :internal}}
+ outcome))
+ (is (= "Something went wrong."
+ (#'agent/terminal-error-message [{:type :tool-output :result outcome}])))))))))
+
(deftest metadata-lookup-failures-propagate-test
(with-mp-and-stubs!
(fn []
@@ -773,6 +801,7 @@
(is (true? (:agent-error? (ex-data e))))
(is (= :query-not-runnable (:error (ex-data e))))
(is (re-find #"`offset` cannot be custom columns" (ex-message e)))
+ (is (str/includes? (ex-message e) "Failing paths: stages[0].expressions[0]:"))
(is (re-find #"non-aggregation expression" (ex-message e)))))))))
(deftest editor-gate-offset-in-filter-surfaces-error-end-to-end-test
@@ -907,7 +936,7 @@
bad (assoc-in good [:stages 0 :breakout 0] [:field {} "PRODUCT_ID"])]
(is (nil? (#'construct/query-not-runnable-explanation good)))
(is (str/includes? (#'construct/query-not-runnable-explanation bad)
- "[:stages 0 :breakout 0 1 :base-type]: a field reference by name is missing `base-type`")))))))
+ "stages[0].breakout[0][1].base-type: a field reference by name is missing `base-type`")))))))
;;; ============================================================
;;; Step-9 contract: expressions (custom columns)
@@ -1021,7 +1050,10 @@
(is (= {:class :recoverable
:code :metabase.metabot.tools.recoverable.pipeline/invalid-representations-query
:message "Representations query has an invalid structure."
- :recovery []}
+ :recovery [{:uses #{}
+ :text (str "Invalid at stages[0].aggregation[1]: should be a vector, "
+ "clause must be [operator-string, options-map, \u2026args]. "
+ "Fix the named paths.")}]}
(select-keys (tools.error/classify e) [:class :code :message :recovery]))))))))
(deftest aggregation-ref-integer-index-in-order-by-end-to-end-test
@@ -3201,14 +3233,35 @@
invalid (fn [k] {:schema (mc/schema :int) :value "x" :in [:stages 0 k]})
hint #"\. This usually means a field reference is missing its type"]
(testing "identical problems are listed once"
- (is (= "[:stages 0 :alias]: missing `alias`" (explain (missing :alias) (missing :alias)))))
+ (is (= "stages[0].alias: missing `alias`" (explain (missing :alias) (missing :alias)))))
(testing "at most three problems are listed"
(is (= 3 (count (str/split (apply explain (map missing [:a :b :c :d])) #"; ")))))
(testing "problems with a known cause are listed before Malli's own messages"
(is (str/starts-with? (explain (invalid :a) (invalid :b) (invalid :c) (missing :alias))
- "[:stages 0 :alias]: missing `alias`; [:stages 0 :a]: should be an integer")))
+ "stages[0].alias: missing `alias`; stages[0].a: should be an integer")))
(testing "the usual causes are added only when no problem has a known cause"
(is (re-find hint (explain (invalid :a))))
(is (not (re-find hint (explain (invalid :a) (missing :alias))))))
(testing "an explanation with no errors falls back to a generic sentence and the usual causes"
(is (str/starts-with? (explain) "the query does not match the query builder's schema. This usually means")))))
+
+(deftest structural-validation-locations-end-to-end-test
+ (with-mp-and-stubs!
+ (fn []
+ (doseq [[filters details]
+ [[{"op" ">"} "stages[0].filters: invalid type"]
+ [[{"op" ">"} {"op" "<"}]
+ (str "stages[0].filters[0]: should be a vector, "
+ "clause must be [operator-string, options-map, \u2026args]; "
+ "stages[0].filters[1]: should be a vector, "
+ "clause must be [operator-string, options-map, \u2026args]")]]]
+ (let [query (query-data {"lib/type" "mbql/query"
+ "stages" [{"lib/type" "mbql.stage/mbql"
+ "source-table" ["Sample" "PUBLIC" "ORDERS"]
+ "filters" filters}]})
+ hint (str "Invalid at " details ". Fix the named paths.")
+ error (try
+ (tools/with-pipeline-errors (construct/execute-representations-query query))
+ (catch clojure.lang.ExceptionInfo e e))]
+ (is (= (str "Representations query has an invalid structure.\n" hint)
+ (tools.error/recoverable-text (tools.error/classify error) #{}))))))))
diff --git a/test/metabase/metabot/tools/core_test.clj b/test/metabase/metabot/tools/core_test.clj
index 62d5d9c6b18..f8b12cb68bf 100644
--- a/test/metabase/metabot/tools/core_test.clj
+++ b/test/metabase/metabot/tools/core_test.clj
@@ -2,9 +2,11 @@
(:require
[clojure.string :as str]
[clojure.test :refer :all]
+ [metabase.agent-lib.test-util :as agent-lib.tu]
[metabase.metabot.metadata-perms :as metabot.perms]
[metabase.metabot.tools.core :as tools]
[metabase.metabot.tools.error :as tools.error]
+ [metabase.metabot.tools.recovery-hints :as recovery-hints]
[metabase.util.malli.registry :as mr]))
(set! *warn-on-reflection* true)
@@ -399,3 +401,15 @@
(is (=? {:class :unrecoverable :code :internal} (pipeline-failure "boom" {}))))
(testing "a successful body is returned untouched"
(is (= :fine (tools/with-pipeline-errors :fine)))))
+
+(deftest ^:parallel structural-validation-paths-test
+ (let [e (agent-lib.tu/structural-validation-error)
+ data (ex-data e)
+ error (pipeline-failure (ex-message e) (assoc data :agent-error? true))
+ hint "Invalid at stages[0].filters: invalid type. Fix the named paths."]
+ (is (= {:message "Representations query has an invalid structure."
+ :paths "stages[0].filters: invalid type"}
+ (:data error)))
+ (is (= hint (recovery-hints/recovery-hint data)))
+ (is (= (str "Representations query has an invalid structure.\n" hint)
+ (tools.error/recoverable-text error #{})))))
diff --git a/test/metabase/metabot/tools/recoverable/pipeline_test.clj b/test/metabase/metabot/tools/recoverable/pipeline_test.clj
index fbbe28382c4..61c84d5a941 100644
--- a/test/metabase/metabot/tools/recoverable/pipeline_test.clj
+++ b/test/metabase/metabot/tools/recoverable/pipeline_test.clj
@@ -11,8 +11,7 @@
[clojure.test :refer :all]
[metabase.mcp.v2.recovery-hints :as v2-hints]
[metabase.metabot.tools.error :as tools.error]
- ;; loaded for its declarations; the codes are read out of the catalog, not off the vars
- [metabase.metabot.tools.recoverable.pipeline]
+ [metabase.metabot.tools.recoverable.pipeline :as pipeline]
[metabase.metabot.tools.recovery-hints :as v1-hints]))
(set! *warn-on-reflection* true)
@@ -80,6 +79,19 @@
(is (< 20 (count (pipeline-codes))))
(is (contains? (pipeline-codes) :unknown-table))))
+(deftest ^:parallel structural-paths-payload-test
+ (doseq [[paths expected-class] [["stages[0].filters: invalid type" :recoverable]
+ [nil :unrecoverable]
+ [42 :unrecoverable]
+ [{"stages" [{"filters" "invalid type"}]} :unrecoverable]]]
+ (testing (pr-str paths)
+ (let [error (try
+ (tools.error/throw-recoverable! ::pipeline/invalid-representations-query
+ {:message "Invalid query." :paths paths})
+ (catch Throwable e
+ (tools.error/classify e)))]
+ (is (= expected-class (:class error)))))))
+
;;; ===== Can one declaration serve both surfaces? =====
;; The pipeline is shared by Metabot (portable FKs, `read_resource`) and MCP v2 (numeric ids,
diff --git a/test/metabase/metabot/tools_test.clj b/test/metabase/metabot/tools_test.clj
index d87af57977e..ffe00d8a1f9 100644
--- a/test/metabase/metabot/tools_test.clj
+++ b/test/metabase/metabot/tools_test.clj
@@ -323,7 +323,7 @@
(testing label
(is (=? {:class :recoverable
:code :metabase.metabot.tools.recoverable.pipeline/invalid-representations-query
- :text #"^Representations query has an invalid structure\."}
+ :text #"Representations query has an invalid structure\.\nInvalid at .+\. Fix the named paths\."}
(test-util/tool-failure agent-tools/construct-notebook-query-tool
{:query {:lib/type "mbql/query" :stages stages}
:title "Orders"