Skip to content
Guide

Troubleshooting

Fixes for common problems installing Aldwin, opening the web app, and getting answers.

On this page

Find the message you see, or the closest description, and follow the fix. For problems with one model or search provider, its own guide has a troubleshooting table too.

Installing and starting#

"command not found: aldwin" or "command not found: uv"#

The terminal does not know about the new command yet. Close the terminal and open a new one. If it still fails, run uv tool update-shell, then open a new terminal again.

Aldwin says the platform is not supported#

Aldwin runs on macOS and Linux. Windows is not supported yet.

An old version starts#

Run uv tool upgrade aldwin. Your conversations, memory, and settings are kept.

Opening the web app#

Most web app problems come down to the terminal running aldwin web. If in doubt, check that window first.

The browser opened Aldwin without this run's pass. This happens with a bookmark, a typed address, or a tab left over from an earlier run.

Copy the full link from the terminal, the one after Open this link to start, and open it. If you closed that terminal, run aldwin web again for a new link.

The browser did not open#

Copy the link from the terminal into your browser yourself. The web app only accepts connections from the same computer, so it does not work on a server you reach over SSH. Use the terminal app there.

"Open in another tab"#

Only one browser tab can use Aldwin at a time. Select Take over to use this tab. The other tab disconnects.

"Connection lost. Reconnecting…"#

The page lost touch with Aldwin. It tries again on its own a few times, then catches up on anything you missed.

If it shows Aldwin stopped, the web app is no longer running. Run aldwin web again in a terminal, then open the new link.

"Aldwin is not answering"#

The page cannot reach the web app. Check that the terminal running aldwin web is still open and has not stopped with an error.

"aldwin web is already running"#

The web app is already open from another terminal. The message gives its address. Use that one, or stop it with Ctrl-C in its terminal and run aldwin web again.

"Could not listen on…"#

Something else is using the port you asked for with --port. Pick another port, or leave out --port and Aldwin finds a free one.

"Your model is set up, but Aldwin did not start"#

Look at the terminal running aldwin web for the error. A common cause is a local model program, such as Ollama, that stopped. Start it again, then reload the page.

Models and answers#

A reply never arrives, or fails straight away#

  • Check the model. In the web app, open Settings, Models: a status like Key not accepted or Not running says what to fix. In the terminal, type /model.
  • A cloud account with no credit connects fine but fails on the first message. Add credit with the provider.
  • A local model needs its program running. Open Ollama or LM Studio.

Aldwin answers but never does anything#

The model cannot use tools, or is too small to use them reliably. Pick a model marked as able to use tools, or a bigger one. See Choosing a model.

Answers are very slow#

A local model may be too big for your computer. Try a smaller one, or a cloud model.

Aldwin forgets the start of a long conversation#

In a long chat, Aldwin works from notes on the older part. Ask it to look back for the detail you need: it can search the whole chat for the exact words. A model that can read less keeps less, so one with more room helps. See Long chats.

"Aldwin couldn't write notes on this chat just now"#

Writing notes on the older messages failed, for example because the model was busy or slow. Nothing changed and your messages are all still there. Aldwin tries again on its own after a few minutes.

"That message is too long for …"#

The message alone is more than the model can read. Send a shorter one, or choose a model with more room.

"This chat is too long for …, even after making room"#

Even after making room, the chat doesn't fit the model. Start a new chat, or choose a model with more room. Anything Aldwin saved to memory carries over.

"… has too little room to work with Aldwin"#

The model can't hold Aldwin's own instructions and tools. Choose a model with more room in Settings, Models.

Search, apps, and files#

Aldwin says it cannot search the web#

No search provider is connected. See Web search.

An app says "Needs you to sign in"#

Its sign-in ran out. In the web app, open Settings, Tools and select Authenticate on that app. In the terminal, type /connectors and pick the app.

Aldwin cannot read an Office file#

Office files need an add-on. See Office documents.

Aldwin cannot find my files#

It is probably working in a different folder. See Workspace and files.

Aldwin refuses to open a file#

Files that hold passwords and keys, such as .env files, are always off limits. See Safety.

Still stuck#

Report it on GitHub. In the web app, Report a bug at the bottom of the sidebar takes you there. Say what you did, what you expected, and what you saw. Leave out keys, tokens, and private content.

Was this page helpful?