Troubleshooting

This page lists common problems, why they happen and how to fix them. Headings match the error message where Otto shows one.

If your problem isn't here, send feedback with a diagnostic report.

Install from source

Use Node.js 24.21.0 or newer.

pnpm start checks your Node.js version first. Install Node.js 24.21.0 or newer, then run pnpm start again.

Docker errors on start

Docker isn't running, or Compose is too old. Start Docker (on a Mac, open Docker Desktop) and check that docker compose version reports v2.

Run npm run dev to prepare the local database

You ran docker compose yourself before Otto created the database password. Run pnpm start once. It generates OTTO_POSTGRES_PASSWORD and starts the containers for you.

Configure OTTO_VAULT_KEY in server settings before saving a connection.

Otto has no key to encrypt saved credentials. This happens outside macOS, where there's no Keychain. Add a key to .env, then restart Otto.

sed -i.bak "s|^OTTO_VAULT_KEY=.*|OTTO_VAULT_KEY=$(openssl rand -base64 32)|" .env && rm .env.bak

Keep a copy of the key somewhere safe. Saved credentials can't be read without it.

Missing modules after git pull

The update changed dependencies. Run pnpm install --frozen-lockfile, then pnpm start.

The port is in use

Another program uses port 4310. Set another PORT in .env and restart. Otto's database container also needs port 54329 on 127.0.0.1.

You lost the access link

Otto prints a link with #access= when it starts, and your browser keeps the cookie. To get a new link, delete access-key in your data folder (.local/ by default) and restart.

Desktop app

macOS blocks the first launch

Preview builds aren't notarized by Apple yet. Open System Settings → Privacy & Security and select Open Anyway. A managed Mac may need approval from your IT team.

macOS asks for Keychain access after an update

macOS can ask again after Otto is re-signed. Approve it in the macOS dialog. Never type your Mac password into the Otto chat.

Not enough free space to install the runtime

On a Mac, the message says how much free space Otto needs and how much more to free. Otto needs room for the extracted runtime plus 512 MiB, and for the archive while it downloads. Free that space, then retry. Your conversations and settings are kept.

On Windows, the message reads "Otto needs more free disk space to prepare its private computer." Allow at least 20 GB, then select Try again.

Setup fails or stops partway

Retry first. Don't delete the profile, VM, database or runtime cache to fix it. If it still fails, send feedback. If the chat can't open, send the setup error you see instead.

Windows says WSL is missing

Select Install WSL in Otto, approve the administrator request, restart the PC and open Otto again. A device policy can block WSL installation.

Models and apps

Port 1455 is already in use

ChatGPT sign-in receives its callback on port 1455. Another Otto app or another sign-in is using it. Close it, then try again.

Composio says "Invalid API key"

A valid key without the right permissions can show this error. You can't edit a key's permissions, so create a new key with the permissions in Apps and use it instead. Keep using the same Composio project, because connected accounts belong to it.

Channels

WhatsApp needs a public HTTPS callback

Meta delivers WhatsApp messages to a public HTTPS address. Otto on your computer has none, and the desktop app doesn't relay webhooks. Expose only the /api/webhooks/whatsapp route and keep the rest of Otto private.

Telegram doesn't need one. Leave Public HTTPS callback blank and Otto receives Telegram messages locally.

This Telegram bot already uses a webhook

The bot was set up with a webhook elsewhere. Remove that webhook to use local polling, or enter a public URL in Public HTTPS callback to have Otto use a webhook.

Tasks and actions

A scheduled task didn't run

Scheduled tasks run only while Otto is open and your computer is awake. Closing the window keeps Otto running in the menu bar or tray, but Quit Otto stops it. Turn on Open at login in Settings → General if you rely on schedules.

An action shows as uncertain

Otto was interrupted after it started an action, so it can't tell whether the action ran. Otto never runs it again on its own. For a sign-in or payment, Vault → Activity shows "Result unknown".

stateDiagram-v2
  direction LR
  [*] --> Running: approved
  Running --> Done: result known
  Running --> Uncertain: interrupted
  Uncertain --> Checked: Otto checks the result

Ask Otto to check the result in the app or website before you try again. See One use, one result.

Get help

Send feedback with a diagnostic report

Select Send feedback in the chat. In the desktop app, it's also in the menu bar menu. The report goes to the Otto team at n8n.

By default it includes a diagnostic report of your recent chat, actions and their results. Review it, or clear Include diagnostic report before you send. Never add API keys, passwords or your settings file.

To report a bug, use the bug report form. Report a vulnerability privately, as the security policy describes.