diff --git a/src/core/mdn-annotation.js b/src/core/mdn-annotation.js
index f94bc2bdab..6fa864f54f 100644
--- a/src/core/mdn-annotation.js
+++ b/src/core/mdn-annotation.js
@@ -1,5 +1,5 @@
 // @ts-check
-import { fetchAndCache, getIntlData, showError } from "./utils.js";
+import { docLink, fetchAndCache, getIntlData, showError } from "./utils.js";
 import css from "../styles/mdn-annotation.css.js";
 import { html } from "./import-maps.js";
 
@@ -177,7 +177,7 @@ async function getMdnData(key, mdnConf) {
   const res = await fetchAndCache(url, maxAge);
   if (res.status === 404) {
     const msg = `Could not find MDN data associated with key "${key}".`;
-    const hint = "Please add a valid key to `respecConfig.mdn`";
+    const hint = docLink`If using \`mdn: true\`, check that ${"[shortName]"} is set correctly — the MDN key defaults to the spec's shortName. Otherwise, search for your spec's URL in the [MDN spec links map](https://github.com/w3c/mdn-spec-links/blob/main/SPECMAP.json) to find the correct key, then set ${"[mdn]"} to it.`;
     showError(msg, name, { hint });
     return;
   }
diff --git a/tests/spec/core/mdn-annotation-spec.js b/tests/spec/core/mdn-annotation-spec.js
index 91bc1c3157..8c0b494602 100644
--- a/tests/spec/core/mdn-annotation-spec.js
+++ b/tests/spec/core/mdn-annotation-spec.js
@@ -116,4 +116,19 @@ describe("Core - MDN Annotation", () => {
     expect(tagName).toBe("ASIDE");
     expect(classList).toContain("mdn");
   });
+
+  it("shows a helpful hint when the mdn key is not found (404)", async () => {
+    const ops = makeStandardOps({
+      mdn: { baseJsonPath },
+      shortName: "nonexistent-spec-xyz",
+    });
+    const doc = await makeRSDoc(ops, "spec/core/mdn-annotation.html");
+    const error = doc.respec.errors.find(
+      e => e.plugin === "core/mdn-annotation"
+    );
+    expect(error).toBeTruthy();
+    expect(error.hint).toContain("SPECMAP.json");
+    expect(error.hint).toContain("shortName");
+    expect(error.hint).toContain("mdn");
+  });
 });