Settings and help16 / 16
Troubleshooting and common questions
On this page
Start with the message for the operation that failed, then check the project, Agent, and task status. The sections below point you to the right place for common problems.
Setup will not let you enter the workbench
Initial setup requires at least one Agent to be installed, signed in, and verified. Installation alone, or closing the sign-in window, is not enough: the list must show Ready.
Open that Agent's details, resolve any sign-in, network, or verification issue, and check again. See Install and get ready.
A download fails or stays in preparation
Check the network and system HTTP(S) proxy first. Proxy environment variables take precedence; SOCKS proxies are not supported by this mechanism. A preparation status can appear when the download stops receiving data. Watch for updates and use retry if a failure is reported.
If failures recur, copy the Agent diagnostics and note whether the problem occurred while downloading the runtime, installing the Agent, or verifying the connection.
Sign-in succeeded, but the Agent is still unavailable
Noea uses verification results to decide whether an Agent is ready. Check the account or provider, available quota, and model configuration. For OpenCode, refresh the provider list, confirm the connection, and verify again.
If model selection requires a connection first, connect a session and check again. A setting supported by one Agent is not automatically supported by another.
A project will not open
| Situation | What to do |
|---|---|
| The selected folder is not a Noea project. | Use Open Implementation Folder for code, or select the actual project folder for an existing project. |
| The project folder moved. | Select its current location with Open Existing Noea Project. |
| The project folder was deleted. | Restore it from the Trash, Recycle Bin, or a backup before reopening. |
| The configuration is invalid. | Preserve the original content. Inspect the configuration or submit diagnostics; do not overwrite it by initializing again. |
| A newer app version wrote the data. | Update the app, then reopen. |
| The data version is incompatible. | Keep copies of project and app data, then follow the specific message. Do not overwrite incompatible data. |
Intent is readable, but chats will not start
Check the implementation folder in Settings → Current Project → Project. Link one if none is linked, or relocate the original code folder if its old path is inaccessible.
Also check that the Agent is Ready. Readable intent files do not mean the implementation folder and Agent are ready too.
An explanation is missing or seems wrong
Save the intent, then investigate the relevant paragraph or run Explain from the sidebar. If the requirement needs code changes, implement it in chat before investigating.
Previous text refers to intent before an edit. May be outdated means supporting files changed later. Recheck both against the current content; see Keep explanations up to date.
No changes found in the sidebar does not mean all tests pass or no gaps remain.
Explain did not run after implementation
Check Settings → Current Project → Automation → Explain automatically after implementing. Code-only changes in regular chats, Implement Directly, and failed or stopped implementation runs do not trigger it.
Run Explain manually when needed. If a task has ended but still reports failed or unfinished checks, expand the results, address the cause, and run it again. See the complete automatic trigger rules.
A proposal or organization plan cannot be accepted
If a proposal says the document changed, choose Ask Agent to Re-propose on Current Version. For an outdated organization plan, choose Reorganize.
Ordinary proposals let you edit inserted or replacement text, but do not support accepting individual changes or files. Organized drafts are read-only; you can keep proposed deletions before accepting the whole plan.
Should you resend a failed message?
If Noea says the message was not delivered to the Agent, you can retry. If it may have been delivered, inspect the trace and file changes first to avoid duplicate execution.
If the Agent received the message but stopped mid-task, send a new instruction to check the current state and continue. A proposal card marked Implementation not finished also offers Continue Implementing.
Editing a message, branching a chat, or stopping a run does not roll back file changes.
An MCP server or Skill is not taking effect
For MCP, use Test Connection and check the command, URL, authorization, and environment variables indicated by the result. Even after a successful test, confirm that the server is selected in the chat and that the Agent supports its connection method.
MCP configuration changes need an Agent reconnection. Adding or removing a Skill requires a new chat. Explain and organization tasks do not use these extensions. See Add MCP servers and Skills.
Saving fails or a reference will not open
A save conflict means another operation changed the file on disk while you were editing it. Save your current content separately or reload the disk version. Reloading discards unsaved edits.
For a broken reference, check that the file or material still exists and the implementation folder is accessible. If an old explanation no longer matches the document, return to its paragraph to read the latest explanation and investigate again if needed.
Send useful information to the team
Use Feedback in the sidebar to describe your goal, the actual result, and the steps that led to the problem. Leave an email address for follow-up, or contact [email protected].
If diagnostics are needed, export them from Settings → About or copy them from the Agent's details panel. Diagnostics may contain local status and logs, so review them before sharing. Feedback does not automatically attach these files.