Common startup issues

Fixes land in the next v1.0.x patch release; the exact version is TBD at the time of writing.

Quick-reference troubleshooting for issues that cropped up during the v1.0.4 DX test session. Each entry lists the symptom, likely cause, and where the fix lives.

Browser login returns 401 despite correct credentials

Symptom: /desk/login fails with "authentication failed" even though curl POST /api/v1/auth/login (without a Bearer) works.

Cause: The browser is sending a stale Authorization: Bearer ... header from a prior session. The desk frontend seeds its in-memory access token from localStorage at module load; if the server's session/refresh-token store is reset (server restart, container re-deploy, token-rotation), the stale access token gets attached to the login POST itself, and the auth middleware rejects it.

Fix (v1.0.4.1):

• Backend: authMiddleware now skips auth for public auth endpoints (login, refresh, sso/authorize, sso/callback, saml/metadata, saml/acs). Logout remains authenticated. See pkg/api/middleware.go::isPublicAuthPath.
• Frontend: AuthProvider.restore() now calls setAccessToken(null) when no refresh token is present, clearing the orphan on the first mount.

Workaround (if unpatched): Open DevTools → Application → Local Storage, delete moca_access_token and moca_refresh_token, reload.

moca init fails with "Failed to scaffold desk frontend" and no detail

Symptom: moca init prints the headline with no cause; retrying the same path errors with "desk/ directory already exists".

Cause: CLIError.Format silently dropped the wrapped error. The partial desk/ directory from the first failed attempt blocked the second.

Fix (v1.0.4.1):

• CLIError.Format now surfaces the wrapped Err under the Cause section when no explicit .WithCause(...) is set.
• scaffoldDeskWithCleanup removes a partial desk/ on failure, making retry-in-place safe.
• A pre-existence guard at the top of runInit refuses to touch a hand-authored desk/ (asks the user to remove it or pass --skip-desk).

Scaffolded desk/.env has empty VITE_MOCA_SITE=

Symptom: Frontend can't talk to the backend because X-Moca-Site header is empty.

Cause: moca init wrote the desk template with an empty value; moca site use and moca site create did not update it.

Fix (v1.0.4.1): moca site use and moca site create (first site only) now call scaffold.UpdateDeskEnvSite(...) to populate the value. Non-empty existing values are preserved unless force=true.

DocType Builder "created" DocTypes aren't found in the UI

Symptom: Builder says "BookReader created" then immediately "Failed to load DocType: doctype not found". Backend logs show relation "tab_doctype" does not exist.

Cause: The dev handler was reading the site identifier from the wrong context key — a raw string "site" that tenant middleware never sets. It defaulted to "default", which has no tab_doctype table, so registration silently failed.

Fix (v1.0.4.1): Dev handler now reads from SiteFromContext (the canonical typed key) and returns 400 if the site is missing.

DocType Builder-created DocTypes have no REST endpoints

Symptom: On-disk JSON omits api_config; the REST route generator skips the DocType.

Cause: buildDocTypeJSON never emitted the block.

Fix (v1.0.4.1): The builder now injects a default api_config with all allow-* flags enabled and page sizes 20/100 — matching the CLI scaffold template exactly.

Backend logs "leader election: lock lost" every ~15 minutes

Symptom: Benign WARN spam in single-instance dev.

Cause: Transient Redis blips cause the leader's heartbeat to miss once every few minutes. In single-instance mode there's no other process to promote, but the log line fires regardless.

Fix (v1.0.4.1): Log level downgraded from WARN to DEBUG with key and instance attrs. In multi-instance production, alerting should key off "no leader for N minutes" rather than this line.