Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

feat: smart error CTA for failed transcriptions

Gabriel Stein7c0429f05b8a
diff --git a/src/components/ui/TranscriptionItem.tsx b/src/components/ui/TranscriptionItem.tsx
index e726f82ad..eb1f0ff9d 100644
--- a/src/components/ui/TranscriptionItem.tsx
+++ b/src/components/ui/TranscriptionItem.tsx
@@ -3,7 +3,10 @@ import { useTranslation } from "react-i18next";
import { Button } from "./button";
import { Tooltip } from "./tooltip";
import { Copy, Trash2, FileText, FolderOpen, RotateCcw, Loader2, AlertCircle } from "lucide-react";
-import type { TranscriptionItem as TranscriptionItemType } from "../../types/electron";
+import type {
+ TranscriptionItem as TranscriptionItemType,
+ TranscriptionErrorCode,
+} from "../../types/electron";
import { cn } from "../lib/utils";
import { getCachedPlatform } from "../../utils/platform";
@@ -61,6 +64,15 @@ export default function TranscriptionItem({
const hasAudio = item.has_audio === 1;
const showUtilityGroup = hasRawText || hasAudio;
+ const errorCode = item.error_code as TranscriptionErrorCode;
+ const isConfigError =
+ errorCode === "API_KEY_MISSING" ||
+ errorCode === "INVALID_KEY" ||
+ errorCode === "MODEL_NOT_AVAILABLE";
+ const isAuthError = errorCode === "AUTH_EXPIRED" || errorCode === "AUTH_REQUIRED";
+ const isLimitError = errorCode === "LIMIT_REACHED";
+ const isOfflineError = errorCode === "OFFLINE";
+
return (
<div
className={cn(
@@ -91,26 +103,48 @@ export default function TranscriptionItem({
{item.error_message}
</p>
)}
- <p className="text-xs text-muted-foreground mt-1">
- {hasAudio ? (
- <>
+ {isConfigError && (
+ <p className="text-xs text-muted-foreground mt-1">
+ {hasAudio ? (
+ <>
+ <button
+ onClick={() => onOpenSettings?.()}
+ className="text-primary hover:underline cursor-pointer"
+ >
+ {t("controlPanel.history.failedCtaSettings")}
+ </button>{" "}
+ {t("controlPanel.history.failedCtaAndRetry")}
+ </>
+ ) : (
<button
onClick={() => onOpenSettings?.()}
className="text-primary hover:underline cursor-pointer"
>
- {t("controlPanel.history.failedCtaSettings")}
- </button>{" "}
- {t("controlPanel.history.failedCtaAndRetry")}
- </>
- ) : (
+ {t("controlPanel.history.failedCtaSettingsOnly")}
+ </button>
+ )}
+ </p>
+ )}
+ {isAuthError && (
+ <p className="text-xs text-muted-foreground mt-1">
<button
onClick={() => onOpenSettings?.()}
className="text-primary hover:underline cursor-pointer"
>
- {t("controlPanel.history.failedCtaSettingsOnly")}
+ {t("controlPanel.history.failedCtaSignIn")}
</button>
- )}
- </p>
+ </p>
+ )}
+ {isLimitError && (
+ <p className="text-xs text-muted-foreground mt-1">
+ {t("controlPanel.history.failedLimitReached")}
+ </p>
+ )}
+ {isOfflineError && (
+ <p className="text-xs text-muted-foreground mt-1">
+ {t("controlPanel.history.failedOffline")}
+ </p>
+ )}
</div>
</div>
) : (
diff --git a/src/helpers/audioManager.js b/src/helpers/audioManager.js
index 44cfd8bab..457b0e244 100644
--- a/src/helpers/audioManager.js
+++ b/src/helpers/audioManager.js
@@ -594,7 +594,7 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);
// Save failed transcription with audio so the user can retry later
if (this.lastAudioBlob) {
- this.saveFailedTranscription(error.message, metadata);
+ this.saveFailedTranscription(error.message, error.code || null, metadata);
}
}
} finally {
@@ -816,7 +816,11 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);
apiKey = await window.electronAPI.getMistralKey?.();
}
if (!isValidApiKey(apiKey, "mistral")) {
- throw new Error("Mistral API key not found. Please set your API key in the Control Panel.");
+ const err = new Error(
+ "Mistral API key not found. Please set your API key in the Control Panel."
+ );
+ err.code = "API_KEY_MISSING";
+ throw err;
}
} else if (provider === "groq") {
// Prefer store value (user-entered via UI) over main process (.env)
@@ -825,7 +829,11 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);
apiKey = await window.electronAPI.getGroqKey?.();
}
if (!isValidApiKey(apiKey, "groq")) {
- throw new Error("Groq API key not found. Please set your API key in the Control Panel.");
+ const err = new Error(
+ "Groq API key not found. Please set your API key in the Control Panel."
+ );
+ err.code = "API_KEY_MISSING";
+ throw err;
}
} else {
// Default to OpenAI
@@ -836,9 +844,11 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);
apiKey = await window.electronAPI.getOpenAIKey();
}
if (!isValidApiKey(apiKey, "openai")) {
- throw new Error(
+ const err = new Error(
"OpenAI API key not found. Please set your API key in the .env file or Control Panel."
);
+ err.code = "API_KEY_MISSING";
+ throw err;
}
}
@@ -1511,7 +1521,11 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);
},
"transcription"
);
- throw new Error(`API Error: ${response.status} ${errorText}`);
+ const err = new Error(`API Error: ${response.status} ${errorText}`);
+ if (response.status === 401) err.code = "INVALID_KEY";
+ else if (response.status === 429) err.code = "LIMIT_REACHED";
+ else if (response.status >= 500) err.code = "SERVER_ERROR";
+ throw err;
}
let result;
@@ -1860,7 +1874,7 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);
}
}
- async saveFailedTranscription(errorMessage, metadata = {}) {
+ async saveFailedTranscription(errorMessage, errorCode = null, metadata = {}) {
if (!getSettings().dataRetentionEnabled) {
logger.debug("Skipping failed transcription save — data retention disabled", {}, "audio");
this.lastAudioBlob = null;
@@ -1872,6 +1886,7 @@ registerProcessor("pcm-streaming-processor", PCMStreamingProcessor);
const result = await window.electronAPI.saveTranscription("", null, {
status: "failed",
errorMessage,
+ errorCode,
});
if (result?.id && this.lastAudioBlob) {
diff --git a/src/helpers/database.js b/src/helpers/database.js
index a84bdf2fa..3a831f8f5 100644
--- a/src/helpers/database.js
+++ b/src/helpers/database.js
@@ -67,6 +67,11 @@ class DatabaseManager {
} catch (err) {
if (!err.message.includes("duplicate column")) throw err;
}
+ try {
+ this.db.exec("ALTER TABLE transcriptions ADD COLUMN error_code TEXT");
+ } catch (err) {
+ if (!err.message.includes("duplicate column")) throw err;
+ }
this.db.exec(`
CREATE TABLE IF NOT EXISTS custom_dictionary (
@@ -390,15 +395,19 @@ class DatabaseManager {
}
}
- saveTranscription(text, rawText = null, { status = "completed", errorMessage = null } = {}) {
+ saveTranscription(
+ text,
+ rawText = null,
+ { status = "completed", errorMessage = null, errorCode = null } = {}
+ ) {
try {
if (!this.db) {
throw new Error("Database not initialized");
}
const stmt = this.db.prepare(
- "INSERT INTO transcriptions (text, raw_text, status, error_message) VALUES (?, ?, ?, ?)"
+ "INSERT INTO transcriptions (text, raw_text, status, error_message, error_code) VALUES (?, ?, ?, ?, ?)"
);
- const result = stmt.run(text, rawText, status, errorMessage);
+ const result = stmt.run(text, rawText, status, errorMessage, errorCode);
const fetchStmt = this.db.prepare("SELECT * FROM transcriptions WHERE id = ?");
const transcription = fetchStmt.get(result.lastInsertRowid);
@@ -478,13 +487,13 @@ class DatabaseManager {
}
}
- updateTranscriptionStatus(id, status, errorMessage = null) {
+ updateTranscriptionStatus(id, status, errorMessage = null, errorCode = null) {
try {
if (!this.db) throw new Error("Database not initialized");
const stmt = this.db.prepare(
- "UPDATE transcriptions SET status = ?, error_message = ? WHERE id = ?"
+ "UPDATE transcriptions SET status = ?, error_message = ?, error_code = ? WHERE id = ?"
);
- stmt.run(status, errorMessage, id);
+ stmt.run(status, errorMessage, errorCode, id);
return { success: true };
} catch (error) {
debugLogger.error(
diff --git a/src/helpers/ipcHandlers.js b/src/helpers/ipcHandlers.js
index 1e4ebaa53..dfefdeea2 100644
--- a/src/helpers/ipcHandlers.js
+++ b/src/helpers/ipcHandlers.js
@@ -55,7 +55,7 @@ function buildMultipartBody(fileBuffer, fileName, contentType, fields = {}) {
return { body: Buffer.concat(bodyParts), boundary };
}
-function postMultipart(url, body, boundary, headers = {}) {
+function postMultipart(url, body, boundary, headers = {}, timeoutMs = 60000) {
const httpModule = url.protocol === "https:" ? https : http;
return new Promise((resolve, reject) => {
const req = httpModule.request(
@@ -64,6 +64,7 @@ function postMultipart(url, body, boundary, headers = {}) {
port: url.port || (url.protocol === "https:" ? 443 : 80),
path: url.pathname,
method: "POST",
+ timeout: timeoutMs,
headers: {
"Content-Type": `multipart/form-data; boundary=${boundary}`,
"Content-Length": body.length,
@@ -82,6 +83,12 @@ function postMultipart(url, body, boundary, headers = {}) {
});
}
);
+ req.on("timeout", () => {
+ req.destroy();
+ const err = new Error("Cloud request timed out");
+ err.code = "TIMEOUT";
+ reject(err);
+ });
req.on("error", reject);
req.write(body);
req.end();
@@ -1599,9 +1606,13 @@ class IPCHandlers {
if (!info?.hotkey) continue;
if (!usesNativeListener(info.hotkey)) {
- debugLogger.log(`[IPC] Unregistering globalShortcut "${info.hotkey}" (slot "${slot}") for capture mode`);
+ debugLogger.log(
+ `[IPC] Unregistering globalShortcut "${info.hotkey}" (slot "${slot}") for capture mode`
+ );
const { globalShortcut } = require("electron");
- try { globalShortcut.unregister(info.hotkey); } catch {}
+ try {
+ globalShortcut.unregister(info.hotkey);
+ } catch {}
}
}
@@ -1614,7 +1625,9 @@ class IPCHandlers {
// On GNOME, unregister all native keybindings during capture
if (hotkeyManager.isUsingGnome() && hotkeyManager.gnomeManager) {
for (const slot of [...hotkeyManager.gnomeManager.registeredSlots]) {
- debugLogger.log(`[IPC] Unregistering GNOME keybinding (slot "${slot}") for capture mode`);
+ debugLogger.log(
+ `[IPC] Unregistering GNOME keybinding (slot "${slot}") for capture mode`
+ );
await hotkeyManager.gnomeManager.unregisterKeybinding(slot).catch((err) => {
debugLogger.warn(`[IPC] Failed to unregister GNOME slot "${slot}":`, err.message);
});
@@ -1641,7 +1654,10 @@ class IPCHandlers {
} else {
// Exiting capture mode - re-register globalShortcut if not already registered
// Skip for KDE/GNOME/Hyprland — updateHotkey handles re-registration via native path
- const usesNativePath = hotkeyManager.isUsingKDE() || hotkeyManager.isUsingGnome() || hotkeyManager.isUsingHyprland();
+ const usesNativePath =
+ hotkeyManager.isUsingKDE() ||
+ hotkeyManager.isUsingGnome() ||
+ hotkeyManager.isUsingHyprland();
if (effectiveHotkey && !usesNativeListener(effectiveHotkey) && !usesNativePath) {
const { globalShortcut } = require("electron");
const accelerator = effectiveHotkey.startsWith("Fn+")
@@ -1709,18 +1725,28 @@ class IPCHandlers {
`[IPC] Re-registering KDE keybinding "${effectiveHotkey}" after capture mode`
);
const callback = this.windowManager.createHotkeyCallback();
- const result = await hotkeyManager.kdeManager.registerKeybinding(effectiveHotkey, "dictation", callback);
+ const result = await hotkeyManager.kdeManager.registerKeybinding(
+ effectiveHotkey,
+ "dictation",
+ callback
+ );
if (result === true) {
hotkeyManager.currentHotkey = effectiveHotkey;
} else {
- debugLogger.warn(`[IPC] Failed to re-register KDE keybinding "${effectiveHotkey}" after capture mode`, { result });
+ debugLogger.warn(
+ `[IPC] Failed to re-register KDE keybinding "${effectiveHotkey}" after capture mode`,
+ { result }
+ );
}
}
// Re-register non-dictation slots (meeting, agent) that were unregistered on capture enter
for (const [slot, info] of hotkeyManager.slots) {
- if (slot === "dictation" || slot === "cancel" || !info?.hotkey || !info?.callback) continue;
- debugLogger.log(`[IPC] Re-registering slot "${slot}" ("${info.hotkey}") after capture mode`);
+ if (slot === "dictation" || slot === "cancel" || !info?.hotkey || !info?.callback)
+ continue;
+ debugLogger.log(
+ `[IPC] Re-registering slot "${slot}" ("${info.hotkey}") after capture mode`
+ );
await hotkeyManager.registerSlot(slot, info.hotkey, info.callback).catch((err) => {
debugLogger.warn(`[IPC] Failed to re-register slot "${slot}":`, err.message);
});
@@ -2610,7 +2636,9 @@ class IPCHandlers {
};
}
if (data.statusCode !== 200) {
- throw new Error(data.data?.error || `API error: ${data.statusCode}`);
+ const err = new Error(data.data?.error || `API error: ${data.statusCode}`);
+ err.code = "SERVER_ERROR";
+ throw err;
}
return {
@@ -2629,7 +2657,7 @@ class IPCHandlers {
};
} catch (error) {
debugLogger.error("Cloud transcription error", { error: error.message }, "cloud-api");
- return { success: false, error: error.message };
+ return { success: false, error: error.message, code: error.code || null };
}
});
@@ -2743,7 +2771,9 @@ class IPCHandlers {
endpoint = "https://api.openai.com/v1/audio/transcriptions";
}
if (!apiKey && provider !== "custom") {
- throw new Error(`${provider} API key not configured`);
+ const err = new Error(`${provider} API key not configured`);
+ err.code = "API_KEY_MISSING";
+ throw err;
}
const formData = new FormData();
@@ -2759,7 +2789,11 @@ class IPCHandlers {
const response = await fetch(endpoint, { method: "POST", headers, body: formData });
if (!response.ok) {
const errorText = await response.text();
- throw new Error(`${provider} API Error: ${response.status} ${errorText}`);
+ const err = new Error(`${provider} API Error: ${response.status} ${errorText}`);
+ if (response.status === 401) err.code = "INVALID_KEY";
+ else if (response.status === 429) err.code = "LIMIT_REACHED";
+ else if (response.status >= 500) err.code = "SERVER_ERROR";
+ throw err;
}
const data = await response.json();
if (data?.text) {
@@ -2794,6 +2828,12 @@ class IPCHandlers {
{ id, error: error.message },
"audio-storage"
);
+ this.databaseManager.updateTranscriptionStatus(
+ id,
+ "failed",
+ error.message,
+ error.code || null
+ );
return { success: false, error: error.message };
}
});
diff --git a/src/locales/de/translation.json b/src/locales/de/translation.json
index ca6a7edb3..e53870254 100644
--- a/src/locales/de/translation.json
+++ b/src/locales/de/translation.json
@@ -251,6 +251,9 @@
"failedCtaSettings": "Richten Sie Ihren Transkriptionsanbieter ein",
"failedCtaAndRetry": "und klicken Sie dann auf Wiederholen",
"failedCtaSettingsOnly": "Richten Sie Ihren Transkriptionsanbieter in den Einstellungen ein",
+ "failedCtaSignIn": "Erneut anmelden",
+ "failedLimitReached": "Tageslimit erreicht",
+ "failedOffline": "Offline",
"clearAll": "Alle löschen",
"clearAllTitle": "Alle Transkriptionen löschen",
"clearAllDescription": "Alle Transkriptionen und Audiodateien werden dauerhaft entfernt.",
diff --git a/src/locales/en/translation.json b/src/locales/en/translation.json
index 74ea9ef32..f04a0552d 100644
--- a/src/locales/en/translation.json
+++ b/src/locales/en/translation.json
@@ -263,6 +263,9 @@
"failedCtaSettings": "Set up your transcription provider",
"failedCtaAndRetry": "then click retry",
"failedCtaSettingsOnly": "Set up your transcription provider in Settings",
+ "failedCtaSignIn": "Sign in again",
+ "failedLimitReached": "Daily limit reached",
+ "failedOffline": "You're offline",
"rawTranscript": "Raw Transcript",
"clearAll": "Clear all",
"clearAllTitle": "Clear All Transcriptions",
diff --git a/src/locales/es/translation.json b/src/locales/es/translation.json
index 334b024ae..28bcb2799 100644
--- a/src/locales/es/translation.json
+++ b/src/locales/es/translation.json
@@ -251,6 +251,9 @@
"failedCtaSettings": "Configura tu proveedor de transcripción",
"failedCtaAndRetry": "y luego haz clic en reintentar",
"failedCtaSettingsOnly": "Configura tu proveedor de transcripción en Ajustes",
+ "failedCtaSignIn": "Iniciar sesión de nuevo",
+ "failedLimitReached": "Límite diario alcanzado",
+ "failedOffline": "Sin conexión",
"clearAll": "Borrar todo",
"clearAllTitle": "Borrar todas las transcripciones",
"clearAllDescription": "Todas las transcripciones y archivos de audio se eliminarán permanentemente.",
diff --git a/src/locales/fr/translation.json b/src/locales/fr/translation.json
index 7e947a130..e766f31eb 100644
--- a/src/locales/fr/translation.json
+++ b/src/locales/fr/translation.json
@@ -251,6 +251,9 @@
"failedCtaSettings": "Configurez votre fournisseur de transcription",
"failedCtaAndRetry": "puis cliquez sur réessayer",
"failedCtaSettingsOnly": "Configurez votre fournisseur de transcription dans les Paramètres",
+ "failedCtaSignIn": "Se reconnecter",
+ "failedLimitReached": "Limite quotidienne atteinte",
+ "failedOffline": "Hors ligne",
"clearAll": "Tout effacer",
"clearAllTitle": "Effacer toutes les transcriptions",
"clearAllDescription": "Toutes les transcriptions et fichiers audio seront définitivement supprimés.",
diff --git a/src/locales/it/translation.json b/src/locales/it/translation.json
index 54b8a9e20..d024a12b6 100644
--- a/src/locales/it/translation.json
+++ b/src/locales/it/translation.json
@@ -251,6 +251,9 @@
"failedCtaSettings": "Configura il tuo provider di trascrizione",
"failedCtaAndRetry": "poi clicca su riprova",
"failedCtaSettingsOnly": "Configura il tuo provider di trascrizione nelle Impostazioni",
+ "failedCtaSignIn": "Accedi di nuovo",
+ "failedLimitReached": "Limite giornaliero raggiunto",
+ "failedOffline": "Offline",
"clearAll": "Cancella tutto",
"clearAllTitle": "Cancella tutte le trascrizioni",
"clearAllDescription": "Tutte le trascrizioni e i file audio verranno rimossi definitivamente.",
diff --git a/src/locales/pt/translation.json b/src/locales/pt/translation.json
index e3cb7b8ae..369262cf6 100644
--- a/src/locales/pt/translation.json
+++ b/src/locales/pt/translation.json
@@ -223,6 +223,9 @@
"failedCtaSettings": "Configure seu provedor de transcrição",
"failedCtaAndRetry": "e depois clique em tentar novamente",
"failedCtaSettingsOnly": "Configure seu provedor de transcrição nas Configurações",
+ "failedCtaSignIn": "Entrar novamente",
+ "failedLimitReached": "Limite diário atingido",
+ "failedOffline": "Sem conexão",
"clearAll": "Limpar tudo",
"clearAllTitle": "Limpar todas as transcrições",
"clearAllDescription": "Todas as transcrições e arquivos de áudio serão removidos permanentemente.",
diff --git a/src/locales/ru/translation.json b/src/locales/ru/translation.json
index ab8792311..4426a4919 100644
--- a/src/locales/ru/translation.json
+++ b/src/locales/ru/translation.json
@@ -251,6 +251,9 @@
"failedCtaSettings": "Настройте провайдер транскрипции",
"failedCtaAndRetry": "затем нажмите повторить",
"failedCtaSettingsOnly": "Настройте провайдер транскрипции в Настройках",
+ "failedCtaSignIn": "Войти снова",
+ "failedLimitReached": "Дневной лимит достигнут",
+ "failedOffline": "Нет подключения",
"clearAll": "Очистить все",
"clearAllTitle": "Очистить все транскрипции",
"clearAllDescription": "Все транскрипции и аудиофайлы будут безвозвратно удалены.",
diff --git a/src/locales/zh-CN/translation.json b/src/locales/zh-CN/translation.json
index 37bd22eee..40b2cb374 100644
--- a/src/locales/zh-CN/translation.json
+++ b/src/locales/zh-CN/translation.json
@@ -251,6 +251,9 @@
"failedCtaSettings": "设置您的转录服务商",
"failedCtaAndRetry": "然后点击重试",
"failedCtaSettingsOnly": "在设置中配置您的转录服务商",
+ "failedCtaSignIn": "重新登录",
+ "failedLimitReached": "已达每日限额",
+ "failedOffline": "离线",
"clearAll": "全部清除",
"clearAllTitle": "清除所有转录",
"clearAllDescription": "所有转录和音频文件将被永久删除。",
diff --git a/src/locales/zh-TW/translation.json b/src/locales/zh-TW/translation.json
index ee72b743e..9916e2ff4 100644
--- a/src/locales/zh-TW/translation.json
+++ b/src/locales/zh-TW/translation.json
@@ -251,6 +251,9 @@
"failedCtaSettings": "設定您的轉錄服務供應商",
"failedCtaAndRetry": "然後點擊重試",
"failedCtaSettingsOnly": "在設定中配置您的轉錄服務供應商",
+ "failedCtaSignIn": "重新登入",
+ "failedLimitReached": "已達每日限額",
+ "failedOffline": "離線",
"clearAll": "全部清除",
"clearAllTitle": "清除所有轉錄",
"clearAllDescription": "所有轉錄和音訊檔案將被永久刪除。",
diff --git a/src/types/electron.ts b/src/types/electron.ts
index 8d3051e85..2dbb3d49c 100644
--- a/src/types/electron.ts
+++ b/src/types/electron.ts
@@ -2,6 +2,19 @@ export type LocalTranscriptionProvider = "whisper" | "nvidia";
export type TranscriptionStatus = "completed" | "failed" | "pending";
+export type TranscriptionErrorCode =
+ | "TIMEOUT"
+ | "NETWORK"
+ | "SERVER_ERROR"
+ | "OFFLINE"
+ | "AUTH_EXPIRED"
+ | "AUTH_REQUIRED"
+ | "LIMIT_REACHED"
+ | "API_KEY_MISSING"
+ | "INVALID_KEY"
+ | "MODEL_NOT_AVAILABLE"
+ | null;
+
export interface TranscriptionItem {
id: number;
text: string;
@@ -14,6 +27,7 @@ export interface TranscriptionItem {
model: string | null;
status: TranscriptionStatus;
error_message: string | null;
+ error_code: TranscriptionErrorCode;
}
export interface NoteItem {