Troubleshooting

Start with the entry that matches what you see. Many problems can be resolved through the current conversation, connection status, or Settings diagnostics without reinstalling the app or clearing data.

Frequently asked questions

I cannot find an earlier conversation

Press ⌘ + K on macOS or Ctrl + K on Windows and search for a conversation title or a keyword from its messages. Check the workspace and source shown in the results to distinguish conversations with similar names.

If search does not find it, open Settings > Conversation history and check both Archive and Trash. Archived conversations can be restored, as can deleted conversations that remain recoverable in Trash. Session-state snapshots offer another recovery entry, but do not restore every deleted project file.

Retry a failed or incomplete search before concluding that a conversation was deleted.

EvoX opens, but the model does not respond

First check whether the conversation is waiting for approval, sign-in, or a tool result. If there is no waiting prompt, open Settings > AI services:

1. Identify the provider and connection instance used by the current model.
2. Test that instance and preserve the original error.
3. Use the error to check credentials, endpoint URL, model name, or proxy.
4. After the test succeeds, send a short request in a new conversation, then return to the original task.

A website loading successfully does not prove the model endpoint is reachable. EvoX makes bounded retries for eligible transient failures in turns that have not produced output; failed recovery still surfaces an error. When recovery or reconnection is shown, check its state before sending the request again. If tools already returned output, files changed, or an external action occurred, verify the result before retrying. Test the connection you are using before changing multiple model configurations.

A setting was saved, but behavior did not change

Reopen the relevant panel and distinguish a save failure from “saved but not applied.” The latter means the configuration was stored but the running service has not confirmed that it applied the configuration. Use the panel's retry, service-status, or restart action.

Check the scope too: interface language differs from response language, and check the style preset’s scope for titles and deliverable copy. See Settings.

A feature or button is missing

Check the EvoX version, current mode, operating system, and connected capabilities. Some actions require a workspace, others need an existing conversation, and others appear only after the relevant plugin is connected.

If an option is restricted by organization policy, follow that policy rather than overriding local configuration. Check the feature’s documented behavior in the selected mode.

I did not receive a completion notification

Open Settings > Appearance and check sound feedback and notification notices. Sounds, system notifications, and pet bubbles are separate channels; enabling one does not enable all three.

On macOS, use the system-settings entry when notification permission has been denied, then return to EvoX to check again. If the notification service is unavailable, follow the guidance to inspect logs or restart. Use the conversation's status and results to confirm whether work finished.

Stuck or interrupted tasks

Distinguish waiting from failure

1. Inspect the latest tool record: is it running, awaiting approval or sign-in, or already reporting an error?
2. Check file pickers, browser authorization pages, and confirmation dialogs.
3. Supply missing information when requested. If a step failed, address its stated cause first.
4. To interrupt work that is not progressing, use the current response's stop button or press Esc in the conversation composer.

An open menu or input candidate list handles Esc first. To stop multiple running tasks, use ⌘ + Shift + K or Ctrl + Shift + K. Emergency stop does not cancel future scheduled runs.

Continue after stopping

Review completed steps, file changes, and external actions before giving a bounded follow-up. For example:

Check what the previous task completed and list what remains. Preserve the existing files and continue only the unfinished checks. Tell me before sending or publishing anything again.

Stopping does not undo file writes, sent messages, or submitted external requests. Verify uncertain results in the target service before retrying.

If only one conversation is affected, summarize its goal, existing results, and unfinished work before continuing in a new conversation. Do not assume the new conversation automatically has all the old context.

Only part of a swarm finished

Open the swarm pane and inspect failed, waiting, and completed branches separately. Keep results that are still valid, fix the cause of failure, and rerun only unfinished work. If branches finished but the combined answer is missing, ask the lead agent to synthesize their existing records.

Retrying a request, rerunning a task, and regenerating a summary are different recovery actions. For recursive tasks with a recovery entry, inspect the task tree and snapshot first. An ordinary swarm rerun is not snapshot recovery. See Recovery and follow-up.

Browser and web search

The browser pane will not open

Open Settings > Cowork and read the built-in browser's status and unavailable reason. Use the retry action provided. If it points to a background service problem, inspect diagnostics in Advanced settings.

If the pane opens but one website fails, check its URL, network access, and allowed-site scope. Do not open access to every site to work around one address.

My browser sign-ins are missing

Check the identity selected under Settings > Cowork > Browser. EvoX's own browser and everyday Chrome use different environments. Being signed in to Chrome does not sign you in to EvoX's separate browser.

Sign in within the separate environment, or follow Use everyday Chrome to reuse Chrome. Also check session storage settings and whether browsing data was cleared.

Everyday Chrome keeps waiting for a connection

1. Confirm Take over my everyday Chrome is selected and Chrome is running.
2. Check that Playwright Extension is installed, then choose Re-check in EvoX.
3. On the first browser task, click Allow on Chrome's connection page.
4. Return to the original task and check the connection result before retrying.

Extension installation and connection authorization are separate steps. Repeatedly starting the same task does not replace authorization. To invalidate old access, turning off silent connection is not enough; regenerate the token as directed by the extension.

Web search fails or produces no sources

Open Settings > AI services > Web search and verify the selected channel and its configuration. EvoMap uses existing model or built-in channel credentials; Tavily needs an API key; Google needs an API key and search engine ID.

Handle rejected credentials, insufficient quota, rate limits, and network timeouts separately. If switching channels, choose another configured channel and run one search. Confirm that the tool returned sources; an ordinary model answer without sources is not proof of a successful search.

Plugins and attached apps

A plugin is installed, but its tools are unavailable

Use /mcp to inspect MCP status, then check enabled state, connection, and credentials in the plugin details. Installed, enabled, and connected are different states.

1. Complete the account or model-service configuration required by the plugin.
2. Test its connection and resolve expired sign-ins or service startup errors.
3. Confirm the current task can use the plugin, then retry a small operation.

Installing an image or speech plugin is not enough when its provider configuration is incomplete. If tools are still missing, check the current mode and tool availability before collecting diagnostics. See Plugins.

An attached app window cannot be read

Confirm the window is still open and select it again from @ App in the composer. On macOS, check EvoX's Screen Recording permission; check Accessibility permission when reading interface text. Reopen EvoX when the system or app requests it after authorization.

Some apps do not expose readable text, and capture restrictions apply to protected windows. Supply a screenshot or file yourself instead of repeatedly granting permissions or retrying indefinitely. See Attach an app for requirements.

Code and terminal

The terminal does not respond, or commands run in the wrong place

Check whether a command is still running or waiting for input. Do not keep pasting new commands into one that is waiting.

In an idle terminal, these read-only commands check the current directory and repository state:

pwd
git status

In PowerShell, Get-Location also shows the current directory. git status requires a Git repository; “not a Git repository” does not mean the terminal is broken.

For an isolated working copy, verify its actual directory and branch. Do not assume it shares all uncommitted files and dependencies with the original project. Check the project's installation and startup instructions when commands behave unexpectedly.

If only the terminal view is affected, try closing and reopening the pane. Save work and account for running tasks before restarting the app or background service.

The terminal cannot find the EvoX command

Open Settings > Advanced > Command line and refresh its status. If it is missing or needs repair, use the installation or repair button, then reopen the terminal to verify.

If the status indicates another command is taking precedence, inspect the path resolved by your shell:

Compare the result with the installation status in Settings. Do not delete an unfamiliar program with the same name; confirm its owning application before removing it.

A local preview link does not open

Confirm the project's development server is running and use the address and port from its current startup output. A restart can change the port; an old link does not follow automatically.

• Connection refused: check that the server started and the port is correct.
• Blank page or error: inspect the first error in the development terminal and page console.
• Localhost in a remote task: refers to the machine running the service, identify that machine before connecting. Use the relevant preview entry or port forwarding.
• Port already occupied: identify its owner and choose another port supported by the project instead of terminating an unknown process.

Scheduled tasks and files

A scheduled task did not run on time

Confirm the task is enabled, check its next run time and time zone, then open its latest run record.

Local tasks need the computer on, EvoX and required services available, and the project directory present. If a run started but failed, check model connections, plugin authorization, and directory permissions. Sleep, network loss, and moved directories are distinct from an incorrect schedule.

After a correction, manually run it once only when doing so will not duplicate external actions. Pause related schedules and preserve changes before cleaning up an isolated working copy they use.

The reply says a file was generated, but I cannot find it

Look for an actual file path or artifact attachment. Describing file contents in a response does not mean a file was written to disk.

Check the project, working copy, or execution device that owns the file, then verify its path and name. For files generated remotely, use the relevant download or transfer entry instead of searching only in a local folder with the same name.

A file exists, but the preview looks wrong

Separate file-content problems from preview problems by opening the same file in its native application.

• For Office or PDF font and pagination problems, check available fonts and embedded resources; export again if needed.
• For blank HTML, inspect script errors and relative asset paths. Avoid absolute paths that exist only on the machine that generated it.
• For stale content, confirm the latest file or artifact version is selected, then refresh the preview.

Preserve the original before regenerating it so a preview failure is not mistaken for lost content.

Diagnostics and recovery

Open Settings > Advanced to inspect background service status, the health summary, and configuration checks. Diagnostics distinguish warnings from failures and provide settings, permission, or service-restart actions for some findings.

Use this order:

1. Record the error, time, and current task state.
2. Run diagnostics and address failures relevant to the problem.
3. Refresh checks after the fix to confirm recovery.
4. Verify with a simple request before continuing the original task.

When the background service is unreachable, inspect the service status obtained independently by the desktop app. An unavailable check or a timeout is not a passing result.

Restarting services, clearing history, and restoring defaults are different actions. Do not begin by clearing data. If a reset is necessary, back up important files and read the deletion scope in its confirmation dialog.

Feedback and logs

Open Report a problem from the application menu, or press ⌘ + Shift + U on macOS or Ctrl + Shift + U on Windows. Review the report's screenshots and diagnostics before submitting.

For logs, open the service details in Settings > Advanced and choose Open logs folder or Copy diagnostic information. Use the app entry to locate the logs for that installation rather than guessing a fixed directory. About in the application menu shows the version.

Include the following:

Problem: what you did and what went wrong
Environment: EvoX version, operating system, and mode
Time: when it happened, including the time zone
Steps: how to reproduce it from a working state
Expected: what should have happened
Actual: error text, screenshot, or failure state
Attempted fixes: what you tried and the outcome

Before sharing logs, screenshots, or copied diagnostic information, remove or redact API keys, tokens, conversation content, customer information, and sensitive local paths containing usernames or internal project names. Include only what is needed for diagnosis, not entire working directories or complete chat histories.

In a conversation, distinguish the feedback-drafting prompt produced by /feedback from report submission. It does not confirm submission. Use the submission result in the problem-report dialog as confirmation.

Diagnose by connection

Identify the failing connection before changing settings. Models, search, browsers, plugins, and the EvoMap Hub have different connections; success in one does not prove the others work.

Locate the failure

Start with four checks

1. Note the failed action and time; retain a redacted error.
2. Open the relevant panel and confirm account, endpoint, and instance.
3. Use that connection's test or retry control.
4. Repeat the original small request to verify recovery.

Change one relevant setting at a time. Switching the model, proxy, and credential together makes the cause harder to identify.

Proxy and background services

Inspect proxy configuration and its effective state in advanced settings. A website opening in your usual browser does not prove the background service follows the same network path.

Reconnect or restart the relevant service when instructed. Check dependencies separately for model connections, search services, and local MCP processes.

Browser connections

The EvoX dedicated browser and everyday Chrome are different identities. Sign in separately to websites in the dedicated environment; everyday Chrome requires an extension and connection authorization.

An installed extension is not necessarily authorized. See Using everyday Chrome for the complete procedure.

Respond to the error type

If a failed action involved a remote write, query its actual state before retrying to avoid duplicate messages or records.

Share useful diagnostics

Include system, app version, connection type, time, expected behavior, actual behavior, and a redacted error. Do not attach full secrets, tokens, or private logs.

For proxy and service settings, see Network and background operation.

EvoX Docs · Features · Reference