how to contribute debugging

Debugging

Desktop flags

Two environment flags shape the desktop shell in desktop/main.ts.

SENTRA_DESKTOP_DEBUG=1 attaches renderer diagnostics to the main window:

• console-message logs each renderer console line as [renderer:<level>] <source>:<line> <message>.
• did-fail-load logs [renderer:did-fail-load] <code> <description> <url>.
• render-process-gone logs [renderer:gone] <reason> <exitCode>.

SENTRA_DESKTOP_SMOKE=1 (also --smoke or the Chromium smoke switch) hides the window and exits the app after the first load, or after a 2000 ms fallback. This is what pnpm run desktop:smoke sets to boot-check the built shell without a visible UI.

Failure classification

desktop/ipc/optimizer-failure.ts maps raw provider errors into an OptimizerFailure record with a code, a stage (prepare or stream), a retryable flag, and a publicMessage. classifyOptimizerFailure reads the lowercased error message:

Pattern	Code	Retryable
401 / 403 / invalid api key / authentication	PROVIDER_AUTH	no
429 / rate limit	RATE_LIMIT	yes
timeout / timed out / abort	TIMEOUT	yes
fetch failed / network / econn	NETWORK	yes
anything else	UNKNOWN	no

Two constant failures are exported for the prepare stage: quotaExceededFailure (QUOTA_EXCEEDED) and modelAccessFailure (MODEL_ACCESS), both non-retryable.

Logging

lib/logger.ts exposes logger.error and logger.warn. Each call builds a structured entry with level, the caller's route context, message, and an ISO timestamp. When NEXT_PUBLIC_SENTRY_DSN is set, logger.error also calls Sentry.captureException with the route as a tag. In development it prints [route] message stack; otherwise it prints JSON. There is no file logging infrastructure: output goes to the console or to Sentry only.

The main process also warns once at startup when no desktop provider key is loaded: appendDesktopEnvWarning prints the current fallback provider and tells the operator to set the matching key in .env.local, process env, or OS env.

Common failures

• Missing provider key: getProvider in lib/llm/provider-registry.ts throws No API key provided for <PROVIDER> for every provider except LOCAL. The shell reports providerReadiness.status === 'missing', shows the Provider Missing badge, and sets modelChip to env-required.
• Provider auth: surfaces as PROVIDER_AUTH. Update the configured provider key and retry.
• Rate limit: surfaces as RATE_LIMIT. Retry shortly.
• Timeout: surfaces as TIMEOUT. Retry the request.
• Network: surfaces as NETWORK. Check connectivity and retry.
• Desktop provider not ready: lib/llm/provider-readiness.ts resolves the guest provider from the available keys, preferring the requested provider and falling back to OPENAI then the first available. With no key at all the status is missing and activeProvider is null.

When a real provider reply looks wrong, start from the OptimizerFailure code, then confirm the model and base URL resolved by getScopedProviderOverrides in lib/llm/provider-registry.ts. See Configuration for the environment names.