Troubleshooting
What Newen's messages mean, and where to look when something goes wrong.
An agent is missing
Section titled “An agent is missing”Newen offers the agents it finds on your PATH. If the one you want is not there, check that its program (claude, codex, opencode or hermes) runs in a terminal, then Check again on the No agent installed page, or restart Newen. A program elsewhere can be set in Settings › (agent) › Program.
Newen started from a desktop launcher may see a shorter PATH than your terminal: set the program’s full path there.
A session failed
Section titled “A session failed”| Message | What happened |
|---|---|
| could not start claude: … | The program could not run: wrong path, missing, or not executable |
| the agent exited with code 1 | The agent stopped with an error; try again, or run the CLI in a terminal to see why |
| Newen was tested with …; this version may behave differently. | Your CLI is a version Newen was not tested with. It still runs; if something looks off, try a tested version |
If an agent asks you to sign in, do it from Settings › Accounts.
The browser
Section titled “The browser”- The agent’s browser opens web pages only: the agent tried a
file:or other address; give it anhttpone. - On Linux the pane needs a Chromium on your
PATH, or Native view on. Set one in Settings › Browser › Chromium, or withNEWEN_CHROME. - On Ubuntu 23.10 and later the shipped Chromium runs without its sandbox and says so in its log,
chromium.log, in the browser’s folder.
Updates
Section titled “Updates”Update errors show in Settings › System › Updates, and every step is in updates.log in Newen’s data folder.
| Message | What to do |
|---|---|
| Could not reach the update server. | Check your connection; it tries again by itself |
| The download is incomplete: it resumes when retried. | Retry |
| The download does not match what was signed: it was deleted. | Retry; if it repeats, report it |
| The update’s signature is not valid: nothing was installed. | Do not install that file by hand; report it |
| This version has no download for this system. | That release has no build for your platform yet |
| This copy of Newen was not installed with newen –install… | Run newen --install, or update the way you built it |
Disk space
Section titled “Disk space”Storage shows what Newen keeps and frees what is unused. Anything it could not free shows as Not freed: with the reason.
Reporting a problem
Section titled “Reporting a problem”Open an issue on GitHub with your platform, Newen’s version (Settings › System), the agent and its version, and what you saw. updates.log contains no addresses or tokens and can be attached as it is.