Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

feat: add actionable login diagnostics

tianma-ifeac1c5173b2f
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index b80d7160..0969ab0a 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -1,6 +1,6 @@
{
"name": "@edgeever/desktop",
- "version": "1.6.41",
+ "version": "1.6.42",
"desktopName": "EdgeEver",
"private": true,
"description": "Native EdgeEver desktop client",
diff --git a/apps/mobile/app.json b/apps/mobile/app.json
index b629a1e2..9385618f 100644
--- a/apps/mobile/app.json
+++ b/apps/mobile/app.json
@@ -3,7 +3,7 @@
"name": "EdgeEver",
"slug": "edgeever",
"scheme": "edgeever",
- "version": "1.6.41",
+ "version": "1.6.42",
"runtimeVersion": {
"policy": "appVersion"
},
@@ -28,7 +28,7 @@
},
"android": {
"package": "org.edgeever.mobile",
- "versionCode": 50,
+ "versionCode": 51,
"adaptiveIcon": {
"backgroundColor": "#d1fae5",
"backgroundImage": "./assets/icon.png",
diff --git a/apps/web/src/app/App.tsx b/apps/web/src/app/App.tsx
index 2f7f050d..e3ce23ea 100644
--- a/apps/web/src/app/App.tsx
+++ b/apps/web/src/app/App.tsx
@@ -9,13 +9,13 @@ import { PwaIosPrompt } from "@/components/PwaIosPrompt";
import { Button } from "@/components/ui/button";
import {
api,
- ApiRequestError,
cacheDesktopSession,
clearCachedDesktopSession,
getConfiguredDesktopApiBaseUrl,
getCachedDesktopSession,
saveDesktopApiBaseUrl,
} from "@/lib/api";
+import { classifyLoginError, type LoginProblem } from "@/lib/login-error";
import { EVERNOTE_MIGRATION_PATH } from "@/lib/routes";
import { isBrowserOffline } from "@/lib/network-status";
import type { AuthSession } from "@edgeever/shared";
@@ -104,11 +104,7 @@ const AuthenticatedWorkspace = () => {
const loginMutation = useMutation({
mutationFn: async (payload: { instanceUrl?: string; username: string; password: string }) => {
if (desktopBridge?.isAvailable && payload.instanceUrl !== undefined) {
- try {
- await saveDesktopApiBaseUrl(payload.instanceUrl);
- } catch {
- throw new Error(t("login.desktopInstanceUrlInvalid"));
- }
+ await saveDesktopApiBaseUrl(payload.instanceUrl);
}
return api.login({ username: payload.username, password: payload.password });
},
@@ -157,22 +153,44 @@ const AuthenticatedWorkspace = () => {
}
const session = sessionQuery.data;
- const configurationError =
- sessionQuery.error instanceof ApiRequestError
- ? sessionQuery.error.code === "auth_not_configured"
- ? t("login.authNotConfigured")
- : sessionQuery.error.code === "database_not_ready"
- ? t("login.databaseNotReady")
- : t("login.instanceUnavailable")
- : sessionQuery.error
- ? t("login.instanceUnavailable")
- : null;
- const loginError =
- loginMutation.error instanceof ApiRequestError && loginMutation.error.code === "password_hash_invalid"
- ? t("login.passwordHashInvalid")
- : loginMutation.error instanceof Error
- ? loginMutation.error.message
- : null;
+ const problem = loginMutation.error
+ ? classifyLoginError(loginMutation.error, "login")
+ : sessionQuery.error
+ ? classifyLoginError(sessionQuery.error, "session")
+ : null;
+ const problemMessage = (value: LoginProblem) => {
+ switch (value.kind) {
+ case "invalidInstanceUrl":
+ return t("login.desktopInstanceUrlInvalid");
+ case "instanceUnreachable":
+ return t("login.instanceUnreachable");
+ case "instanceApiNotFound":
+ return t("login.instanceApiNotFound");
+ case "invalidCredentials":
+ return t("login.invalidCredentials");
+ case "sessionExpired":
+ return t("login.sessionExpired");
+ case "loginRateLimited":
+ return t("login.loginRateLimited");
+ case "authNotConfigured":
+ return t("login.authNotConfigured");
+ case "databaseNotReady":
+ return t("login.databaseNotReady");
+ case "passwordHashInvalid":
+ return t("login.passwordHashInvalid");
+ case "instanceServerError":
+ return t("login.instanceServerError", { status: value.status });
+ case "requestRejected":
+ return t("login.requestRejected", { status: value.status });
+ case "invalidResponse":
+ return t("login.invalidInstanceResponse");
+ case "unexpected":
+ return t("login.unexpectedError");
+ }
+ };
+ const loginError = problem
+ ? { message: problemMessage(problem), diagnosticCode: problem.diagnosticCode }
+ : null;
if (desktopBridge?.isAvailable && !desktopScopeReady) {
if (desktopScopeError) {
@@ -194,7 +212,6 @@ const AuthenticatedWorkspace = () => {
return (
<Suspense fallback={<AuthLoadingScreen />}>
<LoginScreen
- configurationError={configurationError}
error={loginError}
instanceUrl={desktopBridge?.isAvailable ? configuredDesktopApiBaseUrl : undefined}
isSubmitting={loginMutation.isPending}
diff --git a/apps/web/src/components/LoginScreen.tsx b/apps/web/src/components/LoginScreen.tsx
index d746e76b..7373d8f1 100644
--- a/apps/web/src/components/LoginScreen.tsx
+++ b/apps/web/src/components/LoginScreen.tsx
@@ -6,8 +6,7 @@ import { GitHubRepositoryLink } from "@/components/GitHubRepositoryLink";
import { Input } from "@/components/ui/input";
interface LoginScreenProps {
- configurationError: string | null;
- error: string | null;
+ error: { message: string; diagnosticCode: string } | null;
instanceUrl?: string;
isSubmitting: boolean;
onSubmit: (payload: { instanceUrl?: string; username: string; password: string }) => void;
@@ -25,7 +24,7 @@ const getDefaultLoginCredentials = () => {
return isDemoHost ? DEMO_LOGIN_CREDENTIALS : { username: "admin", password: "" };
};
-export const LoginScreen = ({ configurationError, error, instanceUrl: initialInstanceUrl, isSubmitting, onSubmit }: LoginScreenProps) => {
+export const LoginScreen = ({ error, instanceUrl: initialInstanceUrl, isSubmitting, onSubmit }: LoginScreenProps) => {
const { t } = useTranslation();
const [instanceUrl, setInstanceUrl] = useState(initialInstanceUrl ?? "");
const [username, setUsername] = useState(() => getDefaultLoginCredentials().username);
@@ -63,9 +62,15 @@ export const LoginScreen = ({ configurationError, error, instanceUrl: initialIns
</div>
<form className="space-y-5" onSubmit={handleSubmit}>
- {configurationError ? (
- <div className="rounded-lg border border-amber-200 bg-amber-50 px-4 py-3 text-sm font-medium leading-6 text-amber-900">
- {configurationError}
+ {error ? (
+ <div
+ className="rounded-lg border border-rose-100 bg-rose-50/80 px-3.5 py-3 text-rose-800 transition duration-150 animate-shake"
+ role="alert"
+ >
+ <p className="text-sm font-medium leading-6">{error.message}</p>
+ <p className="mt-1 font-mono text-[11px] text-rose-500">
+ {t("login.diagnosticCode", { code: error.diagnosticCode })}
+ </p>
</div>
) : null}
@@ -107,12 +112,6 @@ export const LoginScreen = ({ configurationError, error, instanceUrl: initialIns
/>
</label>
- {error && (
- <div className="rounded-lg border border-rose-100 bg-rose-50/80 px-3.5 py-2.5 text-xs font-medium text-rose-700 transition duration-150 animate-shake">
- {error}
- </div>
- )}
-
<Button
className="w-full h-11 justify-center rounded-lg bg-emerald-500 hover:bg-emerald-600 text-white font-semibold transition-all duration-200 shadow-[0_8px_20px_-4px_rgb(var(--brand-green-rgb)/0.25)] hover:shadow-[0_12px_24px_-4px_rgb(var(--brand-green-rgb)/0.35)]"
size="md"
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
index 30631f9e..4fed4477 100644
--- a/apps/web/src/lib/api.ts
+++ b/apps/web/src/lib/api.ts
@@ -103,11 +103,23 @@ export const getConfiguredDesktopApiBaseUrl = () => {
return bridgeUrl.replace(/\/$/, "");
};
+export class DesktopInstanceUrlError extends Error {
+ constructor() {
+ super("Desktop instance URL must use http or https");
+ this.name = "DesktopInstanceUrlError";
+ }
+}
+
export const saveDesktopApiBaseUrl = async (value: string) => {
const normalized = value.trim().replace(/\/$/, "");
- const parsed = new URL(normalized);
+ let parsed: URL;
+ try {
+ parsed = new URL(normalized);
+ } catch {
+ throw new DesktopInstanceUrlError();
+ }
if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
- throw new Error("Desktop instance URL must use http or https");
+ throw new DesktopInstanceUrlError();
}
if (getConfiguredDesktopApiBaseUrl() !== normalized) {
diff --git a/apps/web/src/lib/login-error.test.mjs b/apps/web/src/lib/login-error.test.mjs
new file mode 100644
index 00000000..c85ec3af
--- /dev/null
+++ b/apps/web/src/lib/login-error.test.mjs
@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { ApiRequestError, DesktopInstanceUrlError } from "./api.ts";
+import { classifyLoginError } from "./login-error.ts";
+
+describe("login error classification", () => {
+ test("distinguishes invalid URLs and unreachable instances", () => {
+ expect(classifyLoginError(new DesktopInstanceUrlError(), "login")).toEqual({
+ kind: "invalidInstanceUrl",
+ diagnosticCode: "instance_url_invalid",
+ });
+ expect(classifyLoginError(new TypeError("Failed to fetch"), "login")).toEqual({
+ kind: "instanceUnreachable",
+ diagnosticCode: "network_unreachable",
+ });
+ });
+
+ test("distinguishes invalid credentials from an expired session", () => {
+ const unauthorized = new ApiRequestError("Authentication required", 401, "unauthorized");
+ expect(classifyLoginError(unauthorized, "login").kind).toBe("invalidCredentials");
+ expect(classifyLoginError(unauthorized, "session").kind).toBe("sessionExpired");
+ });
+
+ test("preserves actionable server error categories", () => {
+ expect(classifyLoginError(new ApiRequestError("Not found", 404), "login").kind).toBe("instanceApiNotFound");
+ expect(classifyLoginError(new ApiRequestError("Slow down", 429, "login_rate_limited"), "login").kind)
+ .toBe("loginRateLimited");
+ expect(classifyLoginError(new ApiRequestError("Unavailable", 503, "database_not_ready"), "session").kind)
+ .toBe("databaseNotReady");
+ expect(classifyLoginError(new ApiRequestError("Bad gateway", 502), "login")).toEqual({
+ kind: "instanceServerError",
+ diagnosticCode: "http_502",
+ status: 502,
+ });
+ });
+
+ test("identifies responses that are not EdgeEver JSON", () => {
+ expect(classifyLoginError(new SyntaxError("Unexpected token"), "login")).toEqual({
+ kind: "invalidResponse",
+ diagnosticCode: "invalid_instance_response",
+ });
+ });
+});
diff --git a/apps/web/src/lib/login-error.ts b/apps/web/src/lib/login-error.ts
new file mode 100644
index 00000000..dc5e8c51
--- /dev/null
+++ b/apps/web/src/lib/login-error.ts
@@ -0,0 +1,65 @@
+import { ApiRequestError, DesktopInstanceUrlError } from "@/lib/api";
+
+export type LoginErrorPhase = "session" | "login";
+
+export type LoginProblem =
+ | { kind: "invalidInstanceUrl"; diagnosticCode: "instance_url_invalid" }
+ | { kind: "instanceUnreachable"; diagnosticCode: "network_unreachable" }
+ | { kind: "instanceApiNotFound"; diagnosticCode: "edgeever_api_not_found" }
+ | { kind: "invalidCredentials"; diagnosticCode: "invalid_credentials" }
+ | { kind: "sessionExpired"; diagnosticCode: "session_expired" }
+ | { kind: "loginRateLimited"; diagnosticCode: "login_rate_limited" }
+ | { kind: "authNotConfigured"; diagnosticCode: "auth_not_configured" }
+ | { kind: "databaseNotReady"; diagnosticCode: "database_not_ready" }
+ | { kind: "passwordHashInvalid"; diagnosticCode: "password_hash_invalid" }
+ | { kind: "instanceServerError"; diagnosticCode: string; status: number }
+ | { kind: "requestRejected"; diagnosticCode: string; status: number }
+ | { kind: "invalidResponse"; diagnosticCode: "invalid_instance_response" }
+ | { kind: "unexpected"; diagnosticCode: "unexpected_login_error" };
+
+export const classifyLoginError = (error: unknown, phase: LoginErrorPhase): LoginProblem => {
+ if (error instanceof DesktopInstanceUrlError) {
+ return { kind: "invalidInstanceUrl", diagnosticCode: "instance_url_invalid" };
+ }
+
+ if (error instanceof ApiRequestError) {
+ if (error.code === "auth_not_configured") {
+ return { kind: "authNotConfigured", diagnosticCode: "auth_not_configured" };
+ }
+ if (error.code === "database_not_ready") {
+ return { kind: "databaseNotReady", diagnosticCode: "database_not_ready" };
+ }
+ if (error.code === "password_hash_invalid") {
+ return { kind: "passwordHashInvalid", diagnosticCode: "password_hash_invalid" };
+ }
+ if (error.code === "login_rate_limited" || error.status === 429) {
+ return { kind: "loginRateLimited", diagnosticCode: "login_rate_limited" };
+ }
+ if (error.code === "unauthorized" || error.status === 401) {
+ return phase === "login"
+ ? { kind: "invalidCredentials", diagnosticCode: "invalid_credentials" }
+ : { kind: "sessionExpired", diagnosticCode: "session_expired" };
+ }
+ if (error.status === 404) {
+ return { kind: "instanceApiNotFound", diagnosticCode: "edgeever_api_not_found" };
+ }
+ if (error.status >= 500) {
+ return { kind: "instanceServerError", diagnosticCode: `http_${error.status}`, status: error.status };
+ }
+ return {
+ kind: "requestRejected",
+ diagnosticCode: error.code || `http_${error.status}`,
+ status: error.status,
+ };
+ }
+
+ if (error instanceof TypeError) {
+ return { kind: "instanceUnreachable", diagnosticCode: "network_unreachable" };
+ }
+
+ if (error instanceof SyntaxError) {
+ return { kind: "invalidResponse", diagnosticCode: "invalid_instance_response" };
+ }
+
+ return { kind: "unexpected", diagnosticCode: "unexpected_login_error" };
+};
diff --git a/package.json b/package.json
index 76c8989c..ce053032 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "edgeever",
- "version": "1.6.41",
+ "version": "1.6.42",
"private": true,
"type": "module",
"workspaces": [
diff --git a/packages/shared/src/i18n/en-US.ts b/packages/shared/src/i18n/en-US.ts
index d8d05091..5eb70d3a 100644
--- a/packages/shared/src/i18n/en-US.ts
+++ b/packages/shared/src/i18n/en-US.ts
@@ -51,6 +51,16 @@ export const enUS = {
authNotConfigured: "This instance has not completed its security setup. Set EDGE_EVER_AUTH_PASSWORD as a Worker Secret and redeploy. Unauthenticated access stays blocked until it is fixed.",
databaseNotReady: "The database is not ready. Verify that the D1 binding is named DB, apply the remote migrations, and redeploy.",
instanceUnavailable: "This instance is temporarily unavailable. Check the Worker logs and run bun run deploy:doctor to validate the deployment.",
+ instanceUnreachable: "EdgeEver could not reach this instance. Check the address and network, and confirm the instance is running. If it opens in a browser but still fails here, check its HTTPS certificate and CORS configuration.",
+ instanceApiNotFound: "No EdgeEver API was found at this address. Enter the instance root URL, not an admin page or another subpage.",
+ invalidCredentials: "The username or password is incorrect. Check both fields and try again.",
+ sessionExpired: "Your previous login session is no longer valid. Enter your username and password to sign in again.",
+ loginRateLimited: "There have been too many failed login attempts. Wait a moment before trying again.",
+ instanceServerError: "The instance returned a server error (HTTP {{status}}). Try again later or check the instance logs.",
+ requestRejected: "The instance rejected the login request (HTTP {{status}}). Verify the instance address and configuration.",
+ invalidInstanceResponse: "This address did not return a valid EdgeEver response. Confirm that it points to an EdgeEver instance.",
+ unexpectedError: "EdgeEver could not complete the login. Restart the desktop app and try again; if it continues, report the diagnostic code below.",
+ diagnosticCode: "Diagnostic code: {{code}}",
desktopScopeUnavailable: "The desktop local data scope could not be switched. The workspace is paused to protect account data.",
desktopScopeRetry: "Retry",
passwordHashInvalid: "This account's password data is invalid; plaintext passwords are not supported. Follow the deployment guide and run auth:reset-password to reset it safely.",
diff --git a/packages/shared/src/i18n/zh-CN.ts b/packages/shared/src/i18n/zh-CN.ts
index 1b97b392..80b8dbd5 100644
--- a/packages/shared/src/i18n/zh-CN.ts
+++ b/packages/shared/src/i18n/zh-CN.ts
@@ -51,6 +51,16 @@ export const zhCN = {
authNotConfigured: "实例尚未完成安全配置。请在 Worker 中设置 EDGE_EVER_AUTH_PASSWORD Secret,然后重新部署;在修复前不会开放免登录访问。",
databaseNotReady: "数据库尚未就绪。请确认 D1 绑定名称为 DB,并执行远程数据库迁移后重新部署。",
instanceUnavailable: "实例暂时不可用。请查看 Worker 日志并运行 bun run deploy:doctor 检查部署配置。",
+ instanceUnreachable: "无法连接到这个实例。请检查实例地址和网络,并确认实例服务正在运行。如果浏览器能打开但这里仍然失败,请检查 HTTPS 证书和跨域配置。",
+ instanceApiNotFound: "这个地址没有找到 EdgeEver API。请填写实例根地址,不要填写管理页面或其他子页面地址。",
+ invalidCredentials: "账号或密码错误,请检查后重试。",
+ sessionExpired: "之前的登录状态已经失效,请重新输入账号和密码。",
+ loginRateLimited: "登录失败次数过多,请稍等一会儿再试。",
+ instanceServerError: "实例服务返回错误(HTTP {{status}})。请稍后重试,或检查实例服务日志。",
+ requestRejected: "实例拒绝了登录请求(HTTP {{status}})。请检查实例地址和服务配置。",
+ invalidInstanceResponse: "这个地址没有返回有效的 EdgeEver 响应,请确认它指向 EdgeEver 实例。",
+ unexpectedError: "登录过程未能完成。请重启桌面客户端后重试;如果问题持续,请反馈下方诊断代码。",
+ diagnosticCode: "诊断代码:{{code}}",
desktopScopeUnavailable: "桌面本地数据空间暂时无法切换。为保护账户数据,工作区已暂停加载。",
desktopScopeRetry: "重试",
passwordHashInvalid: "该账号的密码数据格式无效,不能使用明文密码。请按照部署指南运行 auth:reset-password 安全重置。",