diff --git a/frontend/src/component/ConnectWalletModal.tsx b/frontend/src/component/ConnectWalletModal.tsx
index f208c47d..0f06e2d8 100644
--- a/frontend/src/component/ConnectWalletModal.tsx
+++ b/frontend/src/component/ConnectWalletModal.tsx
@@ -3,14 +3,13 @@
 import { useEffect, useState } from "react";
 import { X, Check, AlertCircle, ExternalLink } from "lucide-react";
 
-type ModalStep = "idle" | "connecting" | "success" | "error";
+import {
+  type WalletErrorInfo,
+  classifyWalletError,
+  withWalletTimeout,
+} from "@/lib/wallet-errors";
 
-type ErrorType =
-  | "not_installed"
-  | "locked"
-  | "user_rejected"
-  | "wrong_network"
-  | "connection_failed";
+type ModalStep = "idle" | "connecting" | "success" | "error";
 
 interface ConnectWalletModalProps {
   isOpen: boolean;
@@ -33,8 +32,7 @@ export default function ConnectWalletModal({
 }: ConnectWalletModalProps) {
   const [step, setStep] = useState<ModalStep>("idle");
   const [wallets, setWallets] = useState<WalletOption[]>([]);
-  const [error, setError] = useState("");
-  const [errorType, setErrorType] = useState<ErrorType | null>(null);
+  const [errorInfo, setErrorInfo] = useState<WalletErrorInfo | null>(null);
   const [connectedAddress, setConnectedAddress] = useState("");
   const [expandedFaq, setExpandedFaq] = useState(false);
   const [selectedWalletId, setSelectedWalletId] = useState<string | null>(null);
@@ -88,8 +86,7 @@ export default function ConnectWalletModal({
 
   const resetModal = () => {
     setStep("idle");
-    setError("");
-    setErrorType(null);
+    setErrorInfo(null);
     setConnectedAddress("");
     setSelectedWalletId(null);
   };
@@ -102,15 +99,18 @@ export default function ConnectWalletModal({
   const handleWalletSelect = async (walletId: string) => {
     setStep("connecting");
     setSelectedWalletId(walletId);
-    setError("");
-    setErrorType(null);
+    setErrorInfo(null);
 
     try {
       const { StellarWalletsKit } =
         await import("@creit-tech/stellar-wallets-kit/sdk");
 
       StellarWalletsKit.setWallet(walletId);
-      const { address } = await StellarWalletsKit.fetchAddress();
+      // An extension that never answers used to leave this modal on
+      // "connecting" with no way out except closing it.
+      const { address } = await withWalletTimeout(
+        StellarWalletsKit.fetchAddress(),
+      );
 
       setConnectedAddress(address);
       setStep("success");
@@ -120,29 +120,13 @@ export default function ConnectWalletModal({
         onSuccess(address, walletId);
       }, 1200);
     } catch (err: unknown) {
-      const msg = err instanceof Error ? err.message.toLowerCase() : String(err).toLowerCase();
-
-      // Categorize errors
-      if (msg.includes("cancel") || msg.includes("reject") || msg.includes("user closed") || msg.includes("denied")) {
-        // User rejected - reset to idle to let them try again
-        resetModal();
-        return;
-      }
-
-      if (msg.includes("not installed") || msg.includes("not available")) {
-        setErrorType("not_installed");
-        setError("Wallet extension is not installed");
-      } else if (msg.includes("locked")) {
-        setErrorType("locked");
-        setError("Wallet is locked. Please unlock it and try again.");
-      } else if (msg.includes("network") || msg.includes("testnet") || msg.includes("public")) {
-        setErrorType("wrong_network");
-        setError("Please switch to the Stellar Public network in your wallet");
-      } else {
-        setErrorType("connection_failed");
-        setError(err instanceof Error ? err.message : "Connection failed. Please try again.");
-      }
+      const walletName =
+        wallets.find((w) => w.id === walletId)?.name ?? "Your wallet";
 
+      // A declined request used to call resetModal() and return, dropping the
+      // user back at the wallet list with no explanation at all. It is now a
+      // first-class state like any other failure.
+      setErrorInfo(classifyWalletError(err, walletName));
       setStep("error");
     }
   };
@@ -294,39 +278,38 @@ export default function ConnectWalletModal({
         )}
 
         {/* Error */}
-        {step === "error" && (
-          <div className="space-y-6">
+        {step === "error" && errorInfo && (
+          <div className="space-y-6" role="alert" data-testid="wallet-error">
             <div className="text-center">
               <div className="flex justify-center mb-4">
                 <div className="flex h-12 w-12 items-center justify-center rounded-full bg-red-500/10">
                   <AlertCircle className="h-6 w-6 text-red-400" />
                 </div>
               </div>
-              <h3 className="text-lg font-semibold text-white">
-                {errorType === "not_installed"
-                  ? "Wallet Not Installed"
-                  : errorType === "locked"
-                    ? "Wallet Locked"
-                    : errorType === "wrong_network"
-                      ? "Wrong Network"
-                      : "Connection Failed"}
+              <h3
+                className="text-lg font-semibold text-white"
+                data-testid="wallet-error-title"
+              >
+                {errorInfo.title}
               </h3>
-              <p className="mt-2 text-sm text-[#9aa4bc]">{error}</p>
-
-              {errorType === "locked" && (
-                <p className="mt-3 text-xs text-[#4FD1C5]">
-                  Unlock your wallet extension and click retry
-                </p>
-              )}
+              <p
+                className="mt-2 text-sm text-[#9aa4bc]"
+                data-testid="wallet-error-message"
+              >
+                {errorInfo.message}
+              </p>
 
-              {errorType === "wrong_network" && (
-                <p className="mt-3 text-xs text-[#4FD1C5]">
-                  Open your wallet extension and switch to the Stellar Public network
+              {errorInfo.hint && (
+                <p
+                  className="mt-3 text-xs text-[#4FD1C5]"
+                  data-testid="wallet-error-hint"
+                >
+                  {errorInfo.hint}
                 </p>
               )}
             </div>
             <div className="flex gap-3">
-              {errorType === "not_installed" ? (
+              {!errorInfo.canRetry ? (
                 <>
                   <button
                     onClick={resetModal}
diff --git a/frontend/src/lib/wallet-errors.test.ts b/frontend/src/lib/wallet-errors.test.ts
new file mode 100644
index 00000000..eeee6731
--- /dev/null
+++ b/frontend/src/lib/wallet-errors.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  WALLET_CONNECT_TIMEOUT_MS,
+  WalletTimeoutError,
+  classifyWalletError,
+  withWalletTimeout,
+} from "./wallet-errors";
+
+const classify = (message: string, wallet = "Freighter") =>
+  classifyWalletError(new Error(message), wallet);
+
+describe("classifyWalletError", () => {
+  it("reports a declined request as a choice, not a fault", () => {
+    for (const message of [
+      "User rejected the request",
+      "Request denied by user",
+      "User cancelled",
+      "user closed the popup",
+      "Request declined",
+    ]) {
+      const info = classify(message);
+      expect(info.type).toBe("user_rejected");
+      expect(info.canRetry).toBe(true);
+    }
+  });
+
+  it("names the wallet in the message so the user knows where to look", () => {
+    expect(classify("User rejected", "Albedo").message).toContain("Albedo");
+  });
+
+  it("detects a missing extension and does not offer a retry", () => {
+    const info = classify("Freighter is not installed");
+    expect(info.type).toBe("not_installed");
+    // Retrying cannot help until the extension exists.
+    expect(info.canRetry).toBe(false);
+    expect(info.hint).toMatch(/install/i);
+  });
+
+  it("detects a locked wallet", () => {
+    expect(classify("Wallet is locked").type).toBe("locked");
+    expect(classify("Please unlock your wallet").type).toBe("locked");
+  });
+
+  it("detects a timeout from a message", () => {
+    expect(classify("Request timed out").type).toBe("timeout");
+    expect(classify("connection timeout").type).toBe("timeout");
+  });
+
+  it("detects a WalletTimeoutError instance", () => {
+    const info = classifyWalletError(new WalletTimeoutError(30_000), "Freighter");
+    expect(info.type).toBe("timeout");
+    expect(info.canRetry).toBe(true);
+  });
+
+  it("distinguishes a connectivity failure from the wrong Stellar network", () => {
+    // "network request failed" contains the word "network" and used to be
+    // reported as "switch to the Stellar Public network", which is useless
+    // advice for someone whose connection is down.
+    for (const message of [
+      "Failed to fetch",
+      "Network request failed",
+      "NetworkError when attempting to fetch resource",
+      "net::ERR_INTERNET_DISCONNECTED",
+      "You appear to be offline",
+    ]) {
+      expect(classify(message).type).toBe("network");
+    }
+  });
+
+  it("detects the wrong Stellar network from a chain-specific message", () => {
+    for (const message of [
+      "Wallet is on testnet",
+      "Please switch to the public network",
+      "Wrong network selected",
+      "Stellar network mismatch",
+    ]) {
+      expect(classify(message).type).toBe("wrong_network");
+    }
+  });
+
+  it("prefers rejection over any other rule", () => {
+    // A decline is deliberate; labelling it a network fault would be wrong.
+    expect(classify("User rejected: network request failed").type).toBe(
+      "user_rejected",
+    );
+  });
+
+  it("falls back to connection_failed and keeps the original text", () => {
+    const info = classify("Something entirely unexpected happened");
+    expect(info.type).toBe("connection_failed");
+    // An unclassified error is exactly when the raw message is the only clue.
+    expect(info.message).toBe("Something entirely unexpected happened");
+    expect(info.canRetry).toBe(true);
+  });
+
+  it("survives a non-Error value", () => {
+    expect(classifyWalletError("plain string failure").type).toBe(
+      "connection_failed",
+    );
+    expect(classifyWalletError(null).type).toBe("connection_failed");
+    expect(classifyWalletError(undefined).type).toBe("connection_failed");
+  });
+
+  it("matches case-insensitively", () => {
+    expect(classify("WALLET IS LOCKED").type).toBe("locked");
+    expect(classify("User REJECTED").type).toBe("user_rejected");
+  });
+
+  it("gives every branch a title and a message", () => {
+    for (const message of [
+      "User rejected",
+      "not installed",
+      "locked",
+      "timed out",
+      "failed to fetch",
+      "testnet",
+      "mystery",
+    ]) {
+      const info = classify(message);
+      expect(info.title.length).toBeGreaterThan(0);
+      expect(info.message.length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("withWalletTimeout", () => {
+  it("passes a result through when it arrives in time", async () => {
+    await expect(withWalletTimeout(Promise.resolve("ok"), 1000)).resolves.toBe("ok");
+  });
+
+  it("passes a rejection through unchanged", async () => {
+    await expect(
+      withWalletTimeout(Promise.reject(new Error("boom")), 1000),
+    ).rejects.toThrow("boom");
+  });
+
+  it("rejects with WalletTimeoutError when the wallet never answers", async () => {
+    vi.useFakeTimers();
+    try {
+      const pending = new Promise(() => undefined);
+      const raced = withWalletTimeout(pending, 30_000);
+      const assertion = expect(raced).rejects.toBeInstanceOf(WalletTimeoutError);
+
+      await vi.advanceTimersByTimeAsync(30_000);
+      await assertion;
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("has a sane default timeout", () => {
+    expect(WALLET_CONNECT_TIMEOUT_MS).toBeGreaterThan(0);
+  });
+});
diff --git a/frontend/src/lib/wallet-errors.ts b/frontend/src/lib/wallet-errors.ts
new file mode 100644
index 00000000..b89e30f0
--- /dev/null
+++ b/frontend/src/lib/wallet-errors.ts
@@ -0,0 +1,214 @@
+/**
+ * Turns whatever a wallet extension throws into something a user can act on.
+ *
+ * Kept pure and outside the modal so every branch can be tested without
+ * mounting a dialog or stubbing a browser extension.
+ */
+
+export type WalletErrorType =
+  | "not_installed"
+  | "locked"
+  | "user_rejected"
+  | "timeout"
+  | "network"
+  | "wrong_network"
+  | "connection_failed";
+
+export interface WalletErrorInfo {
+  type: WalletErrorType;
+  /** Heading for the error panel. */
+  title: string;
+  /** One sentence saying what went wrong. */
+  message: string;
+  /** What to do about it, when there is something concrete to suggest. */
+  hint?: string;
+  /**
+   * Whether retrying the same wallet could plausibly succeed. False only when
+   * the user must do something outside the app first — installing an
+   * extension — so the panel can offer that instead of a button that will
+   * fail again.
+   */
+  canRetry: boolean;
+}
+
+/** Milliseconds before an unanswered connection request is given up on. */
+export const WALLET_CONNECT_TIMEOUT_MS = 30_000;
+
+export class WalletTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`Wallet did not respond within ${Math.round(timeoutMs / 1000)}s`);
+    this.name = "WalletTimeoutError";
+  }
+}
+
+/**
+ * A genuine connectivity failure, as opposed to the wallet being pointed at
+ * the wrong Stellar network.
+ *
+ * These are matched before the wrong-network rule below, because the phrase
+ * "network request failed" contains the word "network" and used to be
+ * reported as "switch to the Stellar Public network" — advice that does
+ * nothing for someone whose connection is simply down.
+ */
+const NETWORK_FAILURE_PATTERNS = [
+  "failed to fetch",
+  "network request failed",
+  "networkerror",
+  "err_internet",
+  "err_network",
+  "offline",
+  "no internet",
+  "connection refused",
+  "econnrefused",
+];
+
+/** Wrong Stellar network. Requires a chain-specific token, never bare "network". */
+const WRONG_NETWORK_PATTERNS = [
+  "wrong network",
+  "unsupported network",
+  "switch network",
+  "network mismatch",
+  "testnet",
+  "pubnet",
+  "public network",
+  "stellar network",
+];
+
+const REJECTION_PATTERNS = [
+  "reject",
+  "denied",
+  "cancel",
+  "user closed",
+  "declined",
+  "dismissed",
+];
+
+const NOT_INSTALLED_PATTERNS = [
+  "not installed",
+  "not available",
+  "not found",
+  "no wallet",
+  "extension missing",
+];
+
+const LOCKED_PATTERNS = ["locked", "unlock"];
+
+const TIMEOUT_PATTERNS = ["timeout", "timed out", "did not respond"];
+
+function matches(haystack: string, needles: readonly string[]): boolean {
+  return needles.some((needle) => haystack.includes(needle));
+}
+
+export function classifyWalletError(
+  error: unknown,
+  walletName = "wallet",
+): WalletErrorInfo {
+  if (error instanceof WalletTimeoutError) {
+    return {
+      type: "timeout",
+      title: "Wallet Did Not Respond",
+      message: `${walletName} did not answer the connection request.`,
+      hint: "Open the extension to check for a pending prompt, then retry.",
+      canRetry: true,
+    };
+  }
+
+  const raw =
+    error instanceof Error ? error.message : String(error ?? "Unknown error");
+  const text = raw.toLowerCase();
+
+  // Rejection is checked first: a user who declines has not hit a fault, and
+  // any other rule matching their message would mislabel a deliberate choice.
+  if (matches(text, REJECTION_PATTERNS)) {
+    return {
+      type: "user_rejected",
+      title: "Connection Declined",
+      message: `The connection request was declined in ${walletName}.`,
+      hint: "Approve the request in your wallet extension to continue.",
+      canRetry: true,
+    };
+  }
+
+  if (matches(text, NOT_INSTALLED_PATTERNS)) {
+    return {
+      type: "not_installed",
+      title: "Wallet Not Installed",
+      message: `${walletName} is not installed in this browser.`,
+      hint: "Install the extension, then reload this page.",
+      // Retrying cannot help until the extension exists.
+      canRetry: false,
+    };
+  }
+
+  if (matches(text, LOCKED_PATTERNS)) {
+    return {
+      type: "locked",
+      title: "Wallet Locked",
+      message: `${walletName} is locked.`,
+      hint: "Unlock your wallet extension and click retry.",
+      canRetry: true,
+    };
+  }
+
+  if (matches(text, TIMEOUT_PATTERNS)) {
+    return {
+      type: "timeout",
+      title: "Wallet Did Not Respond",
+      message: `${walletName} did not answer the connection request.`,
+      hint: "Open the extension to check for a pending prompt, then retry.",
+      canRetry: true,
+    };
+  }
+
+  if (matches(text, NETWORK_FAILURE_PATTERNS)) {
+    return {
+      type: "network",
+      title: "Connection Problem",
+      message: "Could not reach the network to complete the connection.",
+      hint: "Check your internet connection and retry.",
+      canRetry: true,
+    };
+  }
+
+  if (matches(text, WRONG_NETWORK_PATTERNS)) {
+    return {
+      type: "wrong_network",
+      title: "Wrong Network",
+      message: "Your wallet is set to a different Stellar network.",
+      hint: "Switch to the Stellar Public network in your wallet, then retry.",
+      canRetry: true,
+    };
+  }
+
+  return {
+    type: "connection_failed",
+    title: "Connection Failed",
+    // The original text is kept: an unclassified error is exactly the case
+    // where the raw message is the only clue anyone has.
+    message: raw || "Connection failed. Please try again.",
+    canRetry: true,
+  };
+}
+
+/**
+ * Rejects with {@link WalletTimeoutError} if `promise` has not settled in
+ * `timeoutMs`.
+ *
+ * An extension that never answers used to leave the modal on "connecting"
+ * with no way out but closing it.
+ */
+export function withWalletTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number = WALLET_CONNECT_TIMEOUT_MS,
+): Promise<T> {
+  // The underlying request cannot actually be aborted, so its later rejection
+  // is swallowed to avoid an unhandled rejection after the timeout wins.
+  promise.catch(() => undefined);
+
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new WalletTimeoutError(timeoutMs)), timeoutMs);
+  });
+
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}