Troubleshooting Upsolve Local

Search this page for the words in your terminal. Messages are quoted as Upsolve prints them; <like this> stands for something specific to your machine. Upsolve’s messages write commands as upsolve-analytics <command>. Run them as npx @upsolve-labs/analytics <command>.

Two files answer most questions. npx @upsolve-labs/analytics status says whether the app and the agent respond, and npx @upsolve-labs/analytics logs (or logs dashstra, or logs supervisor) shows what they printed. The files are in ~/.upsolve/logs. If you write to support@upsolve.ai, include the last lines of the one that matches your problem. Nothing in a log is sent anywhere unless you send it.

Before Upsolve starts: the installer

These come from npx @upsolve-labs/analytics itself, before anything is downloaded or run.

Node.js is too old

Upsolve Local needs Node.js 22.19 or newer (or 24.11 or newer); this is Node.js <version>.
Install a current Node.js LTS from https://nodejs.org and run the command again.

Install a newer Node.js (brew install node@24, or the installer from nodejs.org), open a new terminal and check node --version. Node.js 23 is not covered.

Not a supported Mac

Upsolve Local runs on macOS only for now (this is <platform>).
Upsolve Cloud works everywhere: https://upsolve.ai

Upsolve Local runs on Apple silicon and Intel Macs (this machine reports <architecture>).

Linux and Windows are not supported yet. Upsolve Cloud runs anywhere.

It does not know where to download from

This build of the installer does not know where to download Upsolve Local from yet.
Set UPSOLVE_DOWNLOAD_BASE_URL to the download location, or install a released version of @upsolve-labs/analytics.

You are running a pre-release copy of the installer. Run the published package: npx @upsolve-labs/analytics@latest. If you host the downloads yourself, set UPSOLVE_DOWNLOAD_BASE_URL. The checksum still comes from the npm package, so a mirror cannot swap the file.

UPSOLVE_DOWNLOAD_BASE_URL is not a URL: <value>
The download location must use https (got <scheme>//<host>).

Give a full https:// address. Plain http:// is accepted only for localhost, 127.0.0.1 and [::1].

The download fails

The installer retries a failed download twice (three tries in all), pausing between them.

could not reach <host>: <reason>. Trying again (2 of 3)...
<host> answered <status> <reason>
the response had no body
no data for <n> seconds
the connection broke after <n> bytes: <reason>
the download ended after <n> of <size> bytes
Could not download Upsolve Local after 3 tries: <last reason>.
Check your connection and run the command again.

Check that you are online and that a VPN or firewall lets Node.js through. Then run the command again. A partial download is deleted, never reused.

Could not write the download to <path>: <reason>

The installer could not save the file under ~/.upsolve/versions. The disk is usually full, or that folder is not writable by you. Free some space or fix the permissions, then run the command again.

<host> answered 404 Not Found: <url>
That release is not on the download server (yet).

The release you asked for has not been uploaded. Run npx @upsolve-labs/analytics@latest.

The download is larger than the <size> bytes this package expects. It was stopped and nothing was extracted.

The file is not the release this package describes. Nothing was unpacked. Try again later, and contact support@upsolve.ai if it repeats.

The checksum does not match

The downloaded file does not match the checksum built into this package, so it was discarded and nothing was extracted.
  expected sha256 <hash>
  received sha256 <hash>
Do not run it. Try again later; if it repeats, contact Upsolve.

Upsolve checks every download against a SHA-256 checksum that ships inside the npm package, not with the download. A different file is thrown away and never run, and the installer does not retry it, because asking again for a file that failed verification is how a tampered mirror gets a second chance. This happens with a corrupted transfer (try once more), a mirror that is out of date, or a file that was swapped on the way. If it repeats, tell us.

The archive will not unpack

Could not run tar: <reason>
tar failed (<mode>, exit <code>): <tar's own message>
The archive is empty.
The archive contains a path outside its own directory (<path>); nothing was extracted.
The archive unpacked as version <version>, not <expected>; nothing was installed.
The archive has no cli/dist/index.js; nothing was installed.

Upsolve unpacks with macOS’s own /usr/bin/tar. tar failed usually means the disk is full or ~/.upsolve is not writable; free some space and run the command again. The last four mean the download passed its checksum but is not a usable release. Nothing is installed in that case, so it is safe to run the command again; if it repeats, contact support.

It does not have that release

--version needs a release number, e.g. --version 6.24.101.
"<value>" is not a release number (expected something like 6.24.101).

--version picks which release the installer runs. Give it a number such as 6.24.101. (A bare --version or -v prints the installer’s own version.)

This package does not carry release <version>, and it is not installed.
  In this package: <releases>
  Installed:       <releases>
A release's checksum comes from the package of that release. Run:
  npx @upsolve-labs/analytics@<version>

Each npm release of the installer carries the checksums of the releases it knows. To run another one, ask for that package version, as the message says.

This copy of @upsolve-labs/analytics does not carry a release to install.
Install the published package: npx @upsolve-labs/analytics@latest

The installer’s own files are damaged

<file> is not valid JSON (<reason>).
<file> is not usable: <problem>
<file> repeats version <version>, which another manifest already describes.

The npm package you are running is damaged or was edited. Run npx @upsolve-labs/analytics@latest, which fetches a fresh copy.

An unexpected error

Unexpected error: <details>

This is a bug in the installer, not something you did. Please send the whole message to support@upsolve.ai.

Finding and using PostgreSQL

Upsolve looks for PostgreSQL in this order, and takes the first it finds without trying the next: --database-url; the database it used last time (kept in ~/.upsolve/config.json); DATABASE_URL, else the PG* variables (PGHOST, PGUSER and so on); and finally <your macOS user>@localhost:5432. From a server it always uses a database called upsolve.

No PostgreSQL is running

Could not connect to PostgreSQL at <user>@localhost:5432 (<reason>).
No PostgreSQL is answering on this machine.
Upsolve Local keeps its data in your own PostgreSQL (version 14 or newer).
  - Homebrew:      brew install postgresql@16 && brew services start postgresql@16
  - Postgres.app:  open Postgres.app and start a server (https://postgresapp.com)
  - already running somewhere else?  upsolve-analytics start --database-url postgres://USER:PASSWORD@HOST:5432/upsolve

Start a server as the message says, then run the command again. Check with psql postgres -c "select version()". If you use Homebrew, brew services list shows whether it is running.

Could not connect to PostgreSQL at <user>@<host>:<port>/<database> (<reason>).
Check that the server is running and reachable from this machine, or pass a different one with --database-url.

You gave Upsolve an address (or it remembered one), and nothing answers there. Check the host, the port and any firewall or VPN, or give a different --database-url. Upsolve remembers the new one.

Wrong role, password or TLS setting

PostgreSQL at <target> has no role named "<user>".
Create one:   psql postgres -c 'CREATE ROLE "<user>" LOGIN CREATEDB'
or use a role that exists:   upsolve-analytics start --database-url postgres://postgres@localhost:5432/upsolve

PostgreSQL at <target> refused role "<user>" (<reason>).
If it needs a password, put it in the URL (percent-encode special characters):
  upsolve-analytics start --database-url postgres://<user>:PASSWORD@<host>:<port>/upsolve
Upsolve stores the URL, password included, in <path to config.json> (readable only by you).

PostgreSQL at <target> and this client disagree about TLS (<reason>).
If the server requires TLS add ?sslmode=require to the URL; if it does not support it, remove sslmode from the URL.

Could not use PostgreSQL at <target>: <reason>

Fix the role or the URL as the message says. A password with special characters must be percent-encoded in the URL (@ becomes %40, for example). The password is stored in ~/.upsolve/config.json, which only you can read.

The URL is not valid

<where it came from> is not a valid URL. Expected postgres://USER[:PASSWORD]@HOST[:PORT]/DATABASE (percent-encode special characters in the password).
<where it came from> must start with postgres:// or postgresql:// (got "<scheme>//").
--database-url must name a database, e.g. postgres://<user>@localhost:5432/upsolve. Without one Postgres would use a database named after the role.

<where it came from> is --database-url, databaseUrl in config.json, DATABASE_URL or The PG* environment variables. Fix that value.

PostgreSQL is too old

PostgreSQL <version> at <target> is too old: Upsolve Local needs 14 or newer.
Install a newer one (brew install postgresql@16, or Postgres.app) or point at one with --database-url.

The database is not Upsolve’s, or the role cannot use it

Database "<name>" at <target> already contains <n> tables or views ("<schema.table>", ...) and is not an Upsolve Local database, so Upsolve will not run its migrations there.
Use an empty database:   createdb upsolve_local   then   upsolve-analytics start --database-url postgres://<role>@<host>:<port>/upsolve_local

Upsolve only runs in an empty database or one that is already its own, so it can never touch your application’s tables. Create an empty one, as the message says. Your data is not changed.

Role "<role>" cannot create tables in the public schema of database "<name>" (PostgreSQL 15 and newer allow that only to the database owner by default).
Use a database "<role>" owns, or as its owner run:   GRANT CREATE ON SCHEMA public TO "<role>";

Role "<role>" is not allowed to create databases on <target> (<reason>).
Either allow it (as a superuser):   psql postgres -c 'ALTER ROLE "<role>" CREATEDB'
or create an empty database the role owns and pass it:
  createdb -O <role> upsolve
  upsolve-analytics start --database-url postgres://<role>@<host>:<port>/upsolve

Could not create database "<name>" on <target>: <reason>
<target> has neither a "postgres" nor a "template1" database to create "<name>" from. Create an empty database yourself and pass it with --database-url.

Managed PostgreSQL services often do not let your role create databases. Create an empty one yourself and pass it with --database-url.

The database Upsolve used has gone

Database "<name>" recorded in <path to config.json> no longer exists on <target>. This usually follows a Postgres upgrade or reinstall.
Restore it from a backup, or start over with a new one:   upsolve-analytics start --database-url <url>

Upsolve will not quietly start an empty database in place of one that vanished, because that would look like losing your data. Upgrading PostgreSQL (for example Homebrew’s 16 to 17) starts a new, empty server, so the database is not there any more. If you have a backup of the upsolve database, restore it with psql into the database the message names. To start fresh, pass --database-url.

Starting Upsolve

Upsolve is already running

Upsolve is already running (pid <pid>) at http://127.0.0.1:<port>. Stop it first with: upsolve-analytics stop
A previous run left <name> (pid <pid>) running. Clean up with: upsolve-analytics stop

Run npx @upsolve-labs/analytics stop. It also cleans up processes a crashed run left behind. status shows what it sees.

A port is in use

Ports <a>/<b> are busy; using <c>/<d>.
Port <n> is already in use. Stop whatever is using it, or pick another with --port (leave it out and Upsolve takes the next free pair).
--port and --agent-port must be different.
No free pair of ports found starting at <port>/<agent port>. Free some ports or choose others with --port and --agent-port.

The first line is not an error: the default pair (4400 and 4401) is taken, so Upsolve moved to the next free pair and remembers it. A port you pin with --port is used exactly as given, or not at all. The address Upsolve opens is always printed as Upsolve Local is running at <address>.

The database could not be migrated

Migration failed for <file>: <reason>
Upsolve was not started. A file that fails leaves nothing behind, so it is safe to fix the cause and run start again.

Could not prepare the database for migrations: <reason>
No .sql migration files found in <directory>
Lost the migration lock before <file> (the database connection was replaced, or a migration released the lock). Nothing of <file> was run; run the migrations again.

Each migration file runs in its own transaction, so a failing one changes nothing, and you can fix the cause and start again. A few cannot (a file that builds an index concurrently, or manages its own transactions), and then the message says so:

<file> runs outside a transaction, so what came before the failing statement may already be applied. Check what it changed before running start again. To go back, restore the backup taken before this start: upsolve-analytics restore latest

Look at what the file does before starting again, because the part before the error may be in place already. To go back to where you were, restore the backup taken just before this start (see Restoring a backup). Read the reason: a permissions problem or a dropped connection is the usual one. Upsolve waits if another run holds the migration lock (Another migration run is in progress; waiting for it to finish.). If the reason mentions an extension:

Some migrations create PostgreSQL extensions. Connect as a superuser (--database-url), or make sure the server has its contrib extensions installed (Homebrew's postgresql@16 and Postgres.app both do).

Use a superuser role (--database-url postgres://postgres@localhost:5432/upsolve), or install the server’s contrib extensions.

The database is newer than this Upsolve

This database is newer than the Upsolve you are running (<version>).
It was last used by Upsolve <version> and has <n> migrations this version does not have (newest: <file>). Running an older version on it could damage your data, so nothing was started or changed.

A newer release has already upgraded this database, and an older one cannot safely run on it, so Upsolve stops before touching anything. Update with npx @upsolve-labs/analytics@latest. To go back to the older release on purpose, restore the backup taken before the upgrade first (npx @upsolve-labs/analytics restore latest, see Restoring a backup), then run that release.

The backup before an upgrade failed

The backup of your database failed (pg_dump exited with <code>), so the migrations were not applied and nothing was changed.
<pg_dump's own message>
Fix the cause and run start again, or start without a backup:   upsolve-analytics start --no-backup

Before a new release changes your data, Upsolve saves a copy of the database with pg_dump into ~/.upsolve/backups. When that copy fails, it does not upgrade. The lines after the message are pg_dump’s own explanation: usually a pg_dump older than the server (install the client tools that match your PostgreSQL, for example brew install libpq), or a role that cannot read every table. Fix that and start again, or start once with --no-backup if you do not need the copy.

Upsolve could not check the database

Could not check the database before migrating it: <reason>
Upsolve was not started and nothing was changed.

Before migrating, Upsolve reads which migrations the database already has. That read failed for the reason shown, almost always a connection that dropped or a role that cannot read the migrations table. Nothing was changed; fix the cause and start again.

It starts and then does not become healthy

<api and/or dashstra> did not become healthy within <n>s.
<api and/or dashstra> did not become healthy: <name> keeps exiting (last exit code <code>).
--- last lines of <log file> ---
[supervisor] <name> exited (code <code>) after <n>s
[supervisor] restarting <name> in <n>s

The message names the part that failed to come up (api is the app, dashstra is the agent) and prints the end of its log. The reason is almost always in those lines: a port that something else grabbed, a database that stopped, or a setting that is wrong. Upsolve restarts a part that crashes, and gives up on a start after three restarts. A slow Mac can need longer than the default five minutes: --start-timeout 600. Read npx @upsolve-labs/analytics logs supervisor too.

The release is incomplete

Cannot start from <release directory>:
  - <file> is missing; this release is incomplete.

A file of the unpacked release is missing, usually because something deleted part of ~/.upsolve/versions/<release>. Delete that release directory and run npx @upsolve-labs/analytics again to download it afresh.

Messages for people running from a checkout

These appear only if you run Upsolve from a source checkout (start --from-repo) rather than through npx.

There is no release to run. Install one with: npx @upsolve-labs/analytics
--hub2-dist <directory> has no index.html. Build hub2 first, or point at its dist directory.
Only the API is up: no hub2 build was given (--hub2-dist), so there are no pages at that address.
--release and --from-repo cannot be used together.

Using the app

The page says Forbidden

Forbidden: a local session is only issued to the machine Upsolve Local runs on.

Upsolve Local answers only the machine it runs on, and only at http://127.0.0.1:<port> or http://localhost:<port> (the port is printed when it starts). Opening it by another name, through a tunnel or a proxy, or from another computer is refused on purpose: with no login, that check is what keeps other websites and other machines out.

The agent does not answer, or says no AI provider is configured

No AI provider configured — open Settings → AI provider

No AI provider has been saved in the app yet, so there is nothing to send your question to. Open the AI provider settings (Upsolve also asks for one the first time you open the app), pick a provider and paste its key. The next chat uses it, with no restart. Environment variables such as ANTHROPIC_API_KEY, OPENAI_API_KEY, LLM_PROVIDER or OPENROUTER_API_KEY are not read: a key exported in your terminal does not stand in for the one saved in the app, even if it is set when you start Upsolve.

The saved AI provider key could not be read — open Settings → AI provider and enter it again

A provider is saved, but its key cannot be decrypted with the encryptionKey in ~/.upsolve/config.json. This happens when the database came from another install, or config.json was replaced. Enter the key again in the AI provider settings.

The saved AI provider is incomplete — open Settings → AI provider and check it

A provider is saved, but it names no model or no address. An OpenAI-compatible server needs a model name and a base URL: open the AI provider settings and fill in what is missing. Errors from the provider itself (an invalid key, a model that is not available to your account, a rate limit) are shown with the provider’s own wording. Read npx @upsolve-labs/analytics logs dashstra for the full text.

Upgrading to Upsolve Cloud says the cloud does not support it yet

Upsolve Cloud at <address> does not support upgrading from Upsolve Local yet (it answered 404). Try again after the next Upsolve Cloud release.

Upsolve Local asked Upsolve Cloud who you are signed in as, and the cloud has no such page: it is an older release than this Upsolve Local. Your sign-in worked, and nothing was moved. Nothing is wrong with your account or your data. Try again after the next Upsolve Cloud release. If you are running a pre-release build of Upsolve Local, point it at a cloud that has the upgrade by starting it with UPSOLVE_CLOUD_URL (the cloud’s web address) and UPSOLVE_CLOUD_API_URL (its API address) set; if you set those yourself, check that they are the cloud you meant. The message goes on to say that the sign-in key Upsolve Local created is listed in Account settings in Upsolve Cloud. A cloud this old cannot yet be asked to delete it, so Upsolve Local keeps trying and removes it as soon as the cloud can. You can delete it yourself in Account settings at any time.

Upsolve Cloud answered <status> to the account request.
Upsolve Cloud answered the account request in a shape this version does not know.

The cloud understood the request and refused it, or answered in a form this Upsolve Local cannot read. A status of 500 or above is a problem on the cloud’s side: try again in a few minutes. If it keeps answering the same way, write to support@upsolve.ai with the status.

The database refuses the connection

When you press Test & Create Connection, Upsolve connects to your database from your own Mac and shows what the database answered. The reason is in the message:

Could not establish connection: connect ECONNREFUSED 127.0.0.1:5432

Nothing is listening at that host and port. Check the server is running, and that the port is the one it uses (localhost:5432 is filled in for you; a server started by another tool is often on a different port).

Could not establish connection: password authentication failed for user "me"
Could not establish connection: role "me" does not exist

The server is there, but it does not accept that user or password. Check both, and that the role is allowed to connect to the database you named.

Metadata is empty. The metadata query returned no rows for this Postgres connection. Verify the database is reachable and contains user tables.

The connection works, but the database has no tables Upsolve can read, so there is nothing to build the workspace from. The form for the workspace reopens with the connection already chosen: create the tables (or point a new connection at the right database), then press Create.

Commands

Configuration

There is no configuration yet (<path>). It is created the first time you run: upsolve-analytics start
Usage: upsolve-analytics config get <key>
Usage: upsolve-analytics config set <key> <value>
Unknown action "<action>".
Unknown key "<key>". Keys: <list>.
Cannot set "<key>". Settable keys: port, agentPort, databaseUrl, telemetryEnabled.
<key> is a secret and is never printed. It is in <path>.
<key> is a secret: it is generated once and cannot be changed, because a new one would make the data already stored unreadable.

jwtTokenSecret, encryptionKey and filesKey are generated once and cannot be read or changed through the command. Changing the encryption key would make every stored credential unreadable.

<key> must be an integer between 1 and 65535 (got "<value>").
port and agentPort must be different.
<key> must be true or false (got "<value>").
databaseUrl must be a postgres:// URL (got "<value>").
databaseUrl must start with postgres:// or postgresql:// (got "<scheme>//").

A damaged config.json

<path> must contain a JSON object. Fix or restore it; do not delete it if this install holds data, because the encryption key in it cannot be recovered.
<path> is not valid JSON (<reason>). Fix it by hand; do not delete it if this install holds data, because the encryption key in it cannot be recovered.
<path> is not valid:
  - <problem>
Fix the file by hand. Secrets are never regenerated automatically: a new encryptionKey would make every stored credential unreadable.
<path> disappeared while it was read.

config.json holds the key that decrypts what Upsolve stores. Do not delete it to make the error go away: Upsolve would make a new key and could no longer read your connections’ passwords. Open the file in an editor and fix the line the message names, or put back a copy from a backup. Only if this install holds nothing you need can you delete ~/.upsolve/config.json and start over.

A misspelled or unknown option

Every command prints the problem followed by its own usage text (the same text as <command> --help), and exits with status 2. For example, npx @upsolve-labs/analytics start --prot 4500 prints Unknown option '--prot' and the options of start.

Logs, stop and status

Unknown log "<name>". Choose one of: api, dashstra, supervisor.
--lines must be a non-negative integer.
No <name> log yet (<path>). It is created the first time Upsolve starts.
--timeout must be a number of seconds.
--start-timeout must be a positive number of seconds.
Unknown option.
Unknown command "<command>".
Could not claim <path>.

status prints NOT RESPONDING for a part that is running but not answering, and exits with status 3 when Upsolve is not running (0 when it is), so a script can use it. stop waits up to 60 seconds for requests in flight (change it with --timeout), then kills what is left, and says It did not exit in time and was killed. when it had to. A second Ctrl-C in the terminal Upsolve runs in also means stop now. Could not claim <path> means Upsolve could not take its instance lock (~/.upsolve/run/supervisor.pid) after three tries, which happens when two starts race right after a crash. Run npx @upsolve-labs/analytics stop, then start again.

Restoring a backup

Name the backup to restore (a file in the backups directory, a path, or "latest").
There are no backups in <backups directory>. Backups are taken before an upgrade changes your data (and need pg_dump).
No backup "<name>" (looked at that path and in <backups directory>).
psql was not found, and restoring a backup needs it. Install PostgreSQL's client tools (macOS: brew install libpq, or Postgres.app) and run this again.
Upsolve is running (pid <pid>). Stop it first with: upsolve-analytics stop
<database> already has tables in it. A restore needs an empty database; omit --database-url to have one created for you.
The restore failed. <reason>
Its contents are in that database now. Upsolve was not pointed at it; empty it before restoring into it again.

npx @upsolve-labs/analytics restore <backup> loads a backup into a new database and points Upsolve at it; the database you were using is not touched. Name a file from ~/.upsolve/backups, a path to a .sql file, or latest. A backup exists only once an upgrade has taken one, which also needs pg_dump. A restore needs psql, needs Upsolve stopped (npx @upsolve-labs/analytics stop), and needs an empty database: leave out --database-url and Upsolve creates one for you. When the restore itself fails, the new database is removed again and nothing changes. A file that is valid SQL but not an Upsolve backup is the exception for a database you named with --database-url: it ran, so its contents stay in that database, and you need to empty it before restoring into it again. The encryption keys are not in a backup, so keep ~/.upsolve/config.json.

​Before Upsolve starts: the installer

​Node.js is too old

​Not a supported Mac

​It does not know where to download from

​The download fails

​The checksum does not match

​The archive will not unpack

​It does not have that release

​The installer’s own files are damaged

​An unexpected error

​Finding and using PostgreSQL

​No PostgreSQL is running

​Wrong role, password or TLS setting

​The URL is not valid

​PostgreSQL is too old

​The database is not Upsolve’s, or the role cannot use it

​The database Upsolve used has gone

​Starting Upsolve

​Upsolve is already running

​A port is in use

​The database could not be migrated

​The database is newer than this Upsolve

​The backup before an upgrade failed

​Upsolve could not check the database

​It starts and then does not become healthy

​The release is incomplete

​Messages for people running from a checkout

​Using the app

​The page says Forbidden

​The agent does not answer, or says no AI provider is configured

​Upgrading to Upsolve Cloud says the cloud does not support it yet

​The database refuses the connection

​Commands

​Configuration

​A damaged config.json

​A misspelled or unknown option

​Logs, stop and status

​Restoring a backup

Before Upsolve starts: the installer

Node.js is too old

Not a supported Mac

It does not know where to download from

The download fails

The checksum does not match

The archive will not unpack

It does not have that release

The installer’s own files are damaged

An unexpected error

Finding and using PostgreSQL

No PostgreSQL is running

Wrong role, password or TLS setting

The URL is not valid

PostgreSQL is too old

The database is not Upsolve’s, or the role cannot use it

The database Upsolve used has gone

Starting Upsolve

Upsolve is already running

A port is in use

The database could not be migrated

The database is newer than this Upsolve

The backup before an upgrade failed

Upsolve could not check the database

It starts and then does not become healthy

The release is incomplete

Messages for people running from a checkout

Using the app

The page says Forbidden

The agent does not answer, or says no AI provider is configured

Upgrading to Upsolve Cloud says the cloud does not support it yet

The database refuses the connection

Commands

Configuration

A damaged config.json

A misspelled or unknown option

Logs, stop and status

Restoring a backup