Troubleshooting

Troubleshooting

Start with the smallest layer that can explain the symptom: installation, provider route, local bridge, model server, MCP tool, or optional capability. Avoid pasting keys, tokens, private prompts, browser cookies, or full runtime logs into an issue.

Quick Triage

Symptom	First check
Eva will not launch	Run eva from a terminal and confirm the installed standalone build is current
A provider returns an authentication error	Recheck the relevant Settings > Auth entry and provider account permissions
Local model does not answer	Confirm LM Studio is running and its local endpoint matches Settings
Copilot-backed action fails	Run copilot auth login on the same host and confirm the CLI works
Tool/MCP route is unavailable	Open Settings > MCP, refresh status, and test one server at a time
Browser, camera, microphone, or desktop action fails	Check system permissions and the optional dependency for that feature
Workspace run cannot start	Confirm the selected folder is a Git repository and Copilot ACP is configured

Use the Local Diagnostics

The bridge provides local diagnostic endpoints and app surfaces for health, telemetry, recent logs, MCP status, and agent state. In the standalone app, start from Settings and the relevant monitor rather than exposing diagnostic data outside your machine.

Telemetry intentionally records timing, route, and model labels instead of message content or credentials. Local logs may still contain operational context, so redact paths and personal information before sharing an excerpt.

Install or Launch Problems

AppImage Does Not Start

Confirm the installed launcher works:

eva

For a manually downloaded AppImage, make it executable. On hosts without FUSE, launch it with AppImage extraction mode:

./"Eva Standalone-<version>.AppImage" --appimage-extract-and-run --eva-workspace-terminal-v1

For source or packaging setup, use Developer Guide. Do not copy a workspace config.json, .env file, tokens, or browser profile into a new install.

Bridge Fails to Start

The standalone app starts its bridge on a random loopback port. Check that the host has the required Python runtime and that no security policy is blocking local process startup. A bridge failure should show an error instead of silently switching to a different route.

Provider and Model Problems

Copilot ACP

On the same host as Eva, authenticate the CLI:

copilot auth login

Copilot-backed cloud features require a valid Copilot entitlement. A direct OpenAI route can preserve Eva memory and response behavior without Copilot, but ACP-specific MCP retrieval, subagents, and coding workspaces still require the CLI.

Direct Providers

Verify only the key for the provider and feature you selected:

• OpenAI for direct OpenAI models, image generation, TTS/transcription, and semantic embeddings.
• GitHub PAT with Models permission for GitHub Models.
• Google Gemini key for Gemini.
• AWS credentials for Amazon Polly.

Re-enter a key in Settings > Auth rather than placing it in a local source file that might be committed. Check model availability and service-side quota or rate-limit messages when authentication succeeds but requests still fail.

LM Studio

Confirm the local model server is listening at the configured address, usually http://localhost:1234/v1/chat/completions. Start with plain local chat before testing tools. If the model returns malformed tool calls, try a model known to support OpenAI-style tool calling or use a plain-chat workflow.

See Local Mode and MCP for the local setup sequence.

MCP Problems

1. Switch to the intended data mode: Cloud for Copilot-backed retrieval, Local for direct local MCP subprocesses.
2. Refresh MCP status in Settings > MCP.
3. Disable custom servers and verify the base route, then re-enable one server at a time.
4. Verify each server's executable, arguments, local dependencies, and its own credentials without printing secrets.
5. For a legacy-only server, an initial failed modern discovery line can be an expected compatibility probe; Eva respawns it before legacy initialization.

Project MCP modules are discovered from bounded project-relative paths. Enabling one affects future runs for that project, not the global configuration.

Browser, Desktop, Voice, and Camera

Feature	Check
Browser agent	Playwright is installed; browser profile and target site are accessible; sensitive steps need confirmation
Desktop agent	Linux desktop session, pyautogui, visible display, and no competing modal dialogs
Camera	Operating-system camera permission and the OpenCV dependency; camera starts only when explicitly requested
Voice	Microphone permission, selected input device, and selected speech engine credentials/dependencies
Local Voices	./install.sh --voice-deps completed and local voice profile was authorized/configured

Desktop automation has a failsafe: move the pointer to a screen corner to stop PyAutoGUI. Do not use automation for an action you cannot independently review.

Workspace Problems

• Select a real Git repository or let Eva create the managed Eva Ready Workspace; ordinary folders are not accepted.
• Ensure the workspace-enabled standalone route and Copilot ACP are available.
• If agent capacity is full, the run/worktree stays durable and can be dispatched later.
• Failed runs are not automatically replayed after restart; use the explicit Retry action to avoid duplicating remote side effects.
• Inspect the worktree status, final report, Assets, and terminal before archive or discard. Dirty worktrees require explicit confirmation to discard.

Still Stuck?

Open an issue with the Eva version, operating system, selected provider/data mode, exact non-sensitive error message, and minimal reproduction steps. Include whether the issue occurs with a plain chat versus an optional feature. Redact keys, tokens, local paths, private prompts, database data, screenshots with personal data, and logs.