Troubleshooting
Preserve the boundary
A diagnostic is not permission to bind publicly, disable Authelia, run as
loca, expose/home, broaden the workspace, add a wildcard trusted host, or print credentials. Stop the service if diagnosis requires any of those changes.
Web and authentication
| Symptom | Likely cause | Safe action |
|---|---|---|
| Authelia challenge repeats | Edge session, cookie, time, or forward-auth configuration problem | Diagnose the existing edge gate. Do not bypass it or expose port 52320. |
Root or index returns 401 after Authelia succeeds | Automatic root bootstrap did not qualify | Revisit exactly https://deek.loca.zone/ without a query. Verify the trusted public Host/Origin, systemd proof credential, root-only nginx include, and exactly one valid Remote-User; never use a launch URL. |
Browser worked before a restart, then /api fails | A routine restart preserves valid cookies; the authority, browser cookie, or persisted signing secret changed independently | Verify the public authority and managed credential state. A signing-secret rotation intentionally revokes every cookie. |
| Public root bootstrap fails | The path/query is ineligible, Host or Origin is untrusted, proof is missing/invalid, or identity is empty, duplicated, oversized, or contains a control character | Preserve the exact edge and service configuration. Remote-User alone is never sufficient, and a wildcard is not a repair. |
| A loopback cookie does not work publicly | DSH cookies are authority-bound | Visit the bare public URL after Authelia; do not transfer a local cookie or exchange a public launch token. |
| nginx or app was compromised | The independent proxy proof may be known | Replace the proof and restart so the app reads it once at activation. Rotate the separate cookie-signing secret too when every DSH cookie must be revoked. |
The upstream default may serve non-index static assets without its cookie, but the loca edge gates the entire browser surface. In the supervised deployment, proof and identity can bootstrap only the exact query-free root; the native cookie remains required for the index, API, fetch routes, and WebSocket.
Build and startup
| Symptom | Likely cause | Safe action |
|---|---|---|
| Profile boot fails with module-resolution errors and no build hint | Source dependencies exist but the repository build has not completed | Run pnpm run build from the reviewed source root, then promote a new immutable runtime copy. |
| Startup reports missing frontend or client-plugin bundles | The Web artifacts were not built | Rebuild; do not edit generated output by hand. |
| Browser UI is older than the source revision | pnpm dsh does not check artifact freshness | Rebuild and redeploy the same reviewed revision. |
--host 0.0.0.0 exits with a usage error | Upstream intentionally refuses wildcard Web binding | Keep --host 127.0.0.1; nginx is the only public entry point. |
| Unit cannot write persistent state | StateDirectory=deek, DSH_HOME, or the workspace contract is wrong | Stop the service and repair the unit/state declaration. Never make the tree writable by loca or everyone. |
| State appears under another home | DSH_HOME=/var/lib/deek is missing or blank | Stop the service, restore the required environment, and reconcile any stray state without displaying credentials. |
Use systemctl is-active deek.service and the listener check from private page (sign-in required) before opening restricted logs. A supervised launch URL indicates configuration drift because printUrl must be false. Never print or share a proxy proof, cookie-signing secret, browser cookie, provider key, credential file, environment dump, or raw secret-bearing log.
Provider and model errors
Provider recovery follows Subscription Provider Sign-in. Approved onboarding remains DeepSeek, ChatGPT/Codex, and Claude, with independent provider-specific permission before model selection or reauthorization. Shared access requires no extra provider login; do not repeat a completed login or treat a visible card, configured route, or catalog as permission. Holder recovery is historical and owner-specific, not automatic fallback.
| Signal | Meaning | Action |
|---|---|---|
Subscription card says sign-in required / catalog is empty | The dedicated holder has no grant for that provider | Follow Subscription Provider Sign-in; do not enter a paid API key or copy a wallet. |
UNKNOWN_MODEL | The recorded provider/model route no longer exists | Select a configured model or restore the intended provider definition. |
Composer shows Select model and blocks input | A saved default points to a provider that was deleted | Select another configured model. |
Model discovery or refresh returns 401 | The provider rejected its current grant | Preserve the actual error and re-authorize only that dedicated account with the native flow after review. Do not print a token or use another account as fallback. |
| A custom gateway rejects every request | Its OpenAI-compatible request shape differs | Review upstream’s provider compatibility fields; change only the documented route settings. |
| Existing session keeps the previous model | Models are recorded in the session after its first request | Start a new session when the new default must apply. |
Provider changes take effect on the next request and normally need no service restart.
Change summaries after a backend restart
As observed through rc.2-r14, /api/changes.summary returns 404 for sessions older than the current backend process. Summaries are process-local and are lost on restart or release cutover; the response is Change summary unavailable. This is a backend durability defect tracked as D-590, not a repaired frontend path. A session remaining in the session list does not mean its summary survived. Do not retry model work or restart the owner to recover a lost summary; preserve the session/sequence and report the defect.
Phone Settings layout
Release-qualified phone Settings. Older owner releases can retain upstream narrow wrapping/clipped-control behavior at 390 px. The responsive sidebar/theme is documented from rc.2-r10, with contrast and session-keyboard corrections from rc.2-r11. For Models phone behavior, Subscription Provider Sign-in owns the historical 2026-10-29 pxl rc.2-r14 Models-overview observation at 390 × 844 and its exclusions; this is not a blanket General/Models desktop-and-phone fit claim. Check the selected owner’s release in Releases before applying an older workaround. DOM presence alone does not prove that a control is visible.
Subscription callback and native UI startup
These callback details describe the historical loca-holder recovery references in Subscription Provider Sign-in, not shared-instance onboarding. Recovery needs independently authorized owner/account/release review; xAI remains outside approved DeepSeek/Codex/Claude onboarding. A Mac-local callback is not automatically server-local. In those references, Codex/Claude use the specified SSH port forward; the Grok device-code flow needs no tunnel. If SSH refuses an occupied local port, identify its owner; do not kill a listener or expose a public OAuth callback.
The manifest uses crossorigin="use-credentials" through a supported deployment hook. Authelia still guards the manifest, icons, root, and API; a public manifest exception is not the repair. The historical holder deployment record describes a version-pinned non-loopback settings-mirror fix for its three subscription profiles through the existing settings.describe API; this is not a current provider-card count. Subscription Provider Sign-in owns the owner/release-qualified visibility record and separate permission requirements.
Upstream working loopback runs can emit startup net::ERR_ABORTED on /open-in-app/apps and /plugins/events, plus interrupted RPCs during binding/reconnect. These are known residuals, not suppressed errors or a promise that every abort is harmless. The acceptance reference requires the same messages/endpoints/counts as unpatched loopback, later endpoint success, and no additional errors. A new console error, unrecovered endpoint, 4xx/5xx, or CORS failure is a failure to investigate.
Workspace and permissions
| Symptom | Likely cause | Safe action |
|---|---|---|
| New Web UI cannot compose | No workspace has been selected | Add and select only /var/lib/deek/workspace. |
| Intended file is outside the picker | It has not been staged into the dedicated workspace | Copy a reviewed, non-secret working set into the workspace through an operator-controlled process. Do not expose /home or /opt/deek/app. |
| Mutation is denied outside the workspace | The default workspace-write boundary is working | Move only the required disposable input into the workspace; do not switch to unrestricted permissions. |
| A read or network request reaches beyond the workspace | Upstream does not confine reads or network under workspace-write | Remove the resource from process visibility or block it at the host/network boundary. Approval settings are not a substitute. |
| A permission change has no effect on an open session | Stored General settings apply to later Web sessions | Create a new session after reviewing the setting. |
Plugins and profiles
- A successful plugin add, remove, or update changes bundle membership on disk, but the running profile retains the bundle set from startup. Restart after an approved bundle change.
- Ordinary profile/home patch edits can hot-reload when the profile uses
patchReload: live; still review the resulting composed configuration. - An MCP server command and an external plugin execute as trusted host code outside the agent sandbox. Remove the package or patch rather than weakening the sandbox to make it work.
- The loca deployment does not permit ad hoc plugin installation into the live service state. Follow the reviewed immutable-release path in Plugin Model.
Escalation record
Capture only non-secret facts:
- deployed Git revision;
- unit active/inactive result;
- listener address and port;
- public HTTP status before authentication;
- exact error code or redacted message;
- browser authority used;
- whether failure began after a restart, update, provider change, or plugin change.
Never attach a proxy proof, cookie-signing secret, browser cookie, provider/API key, credentials file, environment dump, raw secret-bearing log, or user workspace content.