@@ -49,6 +49,7 @@ const makeHandlerLayer = (
   recorded: RecordedRegistration,
   input: {
     readonly environment?: Record<string, unknown>;
+    readonly updateDesktopDatabaseExitCode?: number;
     readonly xdgMimeExitCode?: number;
     readonly writeError?: PlatformError.PlatformError;
   } = {},
@@ -80,7 +81,11 @@ const makeHandlerLayer = (
               command: childProcess.command,
               args: childProcess.args,
             });
-            return Effect.succeed(mockProcess(input.xdgMimeExitCode ?? 0));
+            const exitCode =
+              childProcess.command === "update-desktop-database"
+                ? (input.updateDesktopDatabaseExitCode ?? 0)
+                : (input.xdgMimeExitCode ?? 0);
+            return Effect.succeed(mockProcess(exitCode));
           }),
         ),
       ),
@@ -169,6 +174,10 @@ describe("DesktopLinuxUrlHandler", () => {
       );
       assert.include(recorded.files[0]?.content, "MimeType=x-scheme-handler/t3code;");
       assert.deepEqual(recorded.commands, [
+        {
+          command: "update-desktop-database",
+          args: ["/home/alice/.local/share/applications"],
+        },
         {
           command: "xdg-mime",
           args: ["default", "t3code-url-handler.desktop", "x-scheme-handler/t3code"],
@@ -207,10 +216,12 @@ describe("DesktopLinuxUrlHandler", () => {
   });
 
   it.effect("never fails startup when registration cannot complete", () => {
+    const desktopDatabaseFailed = emptyRecording();
     const xdgMimeFailed = emptyRecording();
     const writeFailed = emptyRecording();
 
     return Effect.gen(function* () {
+      yield* runRegister(desktopDatabaseFailed, { updateDesktopDatabaseExitCode: 1 });
       yield* runRegister(xdgMimeFailed, { xdgMimeExitCode: 1 });
       yield* runRegister(writeFailed, {
         writeError: PlatformError.systemError({
@@ -222,6 +233,10 @@ describe("DesktopLinuxUrlHandler", () => {
         }),
       });
 
+      assert.deepEqual(
+        desktopDatabaseFailed.commands.map(({ command }) => command),
+        ["update-desktop-database", "xdg-mime"],
+      );
       assert.equal(xdgMimeFailed.files.length, 1);
       assert.deepEqual(writeFailed.commands, []);
     });
 
@@ -17,9 +17,9 @@ import { makeComponentLogger } from "./DesktopObservability.ts";
 // Electron's app.setAsDefaultProtocolClient resolves the desktop id from
 // setDesktopName, which cannot match those files — so the browser keeps
 // prompting "Choose an application" for every OAuth callback. Instead, write
-// our own handler entry pointing at the current AppImage and claim the
-// scheme default via xdg-mime, exactly what the file manager's "set as
-// default" checkbox would record in mimeapps.list.
+// our own handler entry pointing at the current AppImage, refresh the desktop
+// MIME cache so desktop environments recognize that entry as a handler, and
+// use xdg-mime to record it as the scheme default in mimeapps.list.
 export const URL_HANDLER_DESKTOP_ENTRY_NAME = "t3code-url-handler.desktop";
 
 const { logInfo, logWarning } = makeComponentLogger("desktop-linux-url-handler");
@@ -42,6 +42,23 @@ export class DesktopLinuxUrlHandlerRegistrationError extends Schema.TaggedErrorC
 
 const isRegistrationError = Schema.is(DesktopLinuxUrlHandlerRegistrationError);
 
+export class DesktopLinuxUrlHandlerCacheRefreshError extends Schema.TaggedErrorClass<DesktopLinuxUrlHandlerCacheRefreshError>()(
+  "DesktopLinuxUrlHandlerCacheRefreshError",
+  {
+    applicationsDir: Schema.String,
+    exitCode: Schema.optionalKey(Schema.Number),
+    cause: Schema.optionalKey(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    const exitCode =
+      this.exitCode === undefined ? "" : `, update-desktop-database exit code ${this.exitCode}`;
+    return `Failed to refresh the desktop MIME cache at ${this.applicationsDir}${exitCode}.`;
+  }
+}
+
+const isCacheRefreshError = Schema.is(DesktopLinuxUrlHandlerCacheRefreshError);
+
 const escapeDesktopEntryString = (value: string): string =>
   value
     .replaceAll("\\", "\\\\")
@@ -128,6 +145,37 @@ export const make = Effect.gen(function* () {
     ),
   );
 
+  const updateDesktopDatabase = Effect.scoped(
+    Effect.gen(function* () {
+      const command = ChildProcess.make(
+        "update-desktop-database",
+        [environment.linuxApplicationsDir],
+        {
+          stdin: "ignore",
+          stdout: "ignore",
+          stderr: "ignore",
+        },
+      );
+      const handle = yield* spawner.spawn(command);
+      const exitCode = yield* handle.exitCode;
+      if (exitCode !== 0) {
+        return yield* new DesktopLinuxUrlHandlerCacheRefreshError({
+          applicationsDir: environment.linuxApplicationsDir,
+          exitCode,
+        });
+      }
+    }),
+  ).pipe(
+    Effect.mapError((error) =>
+      isCacheRefreshError(error)
+        ? error
+        : new DesktopLinuxUrlHandlerCacheRefreshError({
+            applicationsDir: environment.linuxApplicationsDir,
+            cause: error,
+          }),
+    ),
+  );
+
   const setDefaultHandler = Effect.scoped(
     Effect.gen(function* () {
       const command = ChildProcess.make(
@@ -166,6 +214,21 @@ export const make = Effect.gen(function* () {
       return;
     }
     yield* writeDesktopEntry;
+
+    yield* updateDesktopDatabase.pipe(
+      // Some MIME implementations, including GIO, use mimeinfo.cache to verify
+      // that a desktop entry is associated with a scheme. Cache refresh is
+      // independently best-effort so a missing update-desktop-database executable
+      // does not prevent xdg-mime from recording the requested default.
+      Effect.catch((error) =>
+        logWarning("desktop MIME cache refresh failed", {
+          applicationsDir: environment.linuxApplicationsDir,
+          message: error.message,
+          ...(error.exitCode === undefined ? {} : { exitCode: error.exitCode }),
+        }),
+      ),
+    );
+
     yield* setDefaultHandler;
     yield* logInfo("registered URL scheme handler", { scheme });
   }).pipe(