diff --git a/apps/emqx_dashboard/src/emqx_dashboard_swagger.erl b/apps/emqx_dashboard/src/emqx_dashboard_swagger.erl
index e0b50346d..f700ec146 100644
--- a/apps/emqx_dashboard/src/emqx_dashboard_swagger.erl
+++ b/apps/emqx_dashboard/src/emqx_dashboard_swagger.erl
@@ -239,6 +239,10 @@ parse_spec_ref(Module, Path, Options) ->
             %% better error message
         catch
             error:Reason:Stacktrace ->
+                %% raise a new error with the same stacktrace.
+                %% it's a bug if this happens.
+                %% i.e. if a path is listed in the spec but the module doesn't
+                %% implement it or crashes when trying to build the schema.
                 erlang:raise(
                     error,
                     #{mfa => {Module, schema, [Path]}, reason => Reason},
diff --git a/apps/emqx_dashboard/test/emqx_swagger_requestBody_SUITE.erl b/apps/emqx_dashboard/test/emqx_swagger_requestBody_SUITE.erl
index e6fa62f77..f2ba56e08 100644
--- a/apps/emqx_dashboard/test/emqx_swagger_requestBody_SUITE.erl
+++ b/apps/emqx_dashboard/test/emqx_swagger_requestBody_SUITE.erl
@@ -307,8 +307,11 @@ t_nest_ref(_Config) ->
 
 t_none_ref(_Config) ->
     Path = "/ref/none",
-    ?assertThrow(
-        {error, #{mfa := {?MODULE, schema, [Path]}}},
+    ?assertError(
+        #{
+            mfa := {?MODULE, schema, [Path]},
+            reason := function_clause
+        },
         emqx_dashboard_swagger:parse_spec_ref(?MODULE, Path, #{})
     ),
     ok.
diff --git a/apps/emqx_dashboard/test/emqx_swagger_response_SUITE.erl b/apps/emqx_dashboard/test/emqx_swagger_response_SUITE.erl
index 753aaad7a..cda533cc2 100644
--- a/apps/emqx_dashboard/test/emqx_swagger_response_SUITE.erl
+++ b/apps/emqx_dashboard/test/emqx_swagger_response_SUITE.erl
@@ -277,11 +277,11 @@ t_bad_ref(_Config) ->
 
 t_none_ref(_Config) ->
     Path = "/ref/none",
-    ?assertThrow(
-        {error, #{
+    ?assertError(
+        #{
             mfa := {?MODULE, schema, ["/ref/none"]},
             reason := function_clause
-        }},
+        },
         validate(Path, #{}, [])
     ),
     ok.