Common installation problems

Start with the final error line and the protected installer log path printed near the beginning and end of every run. Remove database URLs, passwords, tokens, and profile codes before sharing a log.

Do not drop or reinitialize PostgreSQL, delete a lockfile, recursively change ownership of a system directory, or add --overwrite-existing merely to make an error disappear. Diagnose the reported boundary first.

The installer prints a Troubleshooting: URL after recognized failures. That link points to the most specific recovery section available. Unexpected failures use this page as the safe starting point; the URL never contains credentials or other installer settings.

Choose the symptom

The install attached to a database that already had accounts

This is the most common surprise on a second install, and it is not a failure. The install directory and the PostgreSQL database have separate lifetimes. Reinstalling, replacing the directory with --overwrite-existing, or pointing a new host at the same --database-url all reuse the existing database — schema updated, every account, sequencing order and record kept.

The seed deliberately never overwrites an account that already exists. If it did, anyone able to run the installer against a connection string could reset that database’s administrator password. So the installer detects the situation and says what it did and did not do:

The selected database already contains SeqDesk accounts.
Existing admin account: admin@example.org (password left unchanged)
  Sign in with the credentials this database was set up with. This install
  neither generated nor stored a password for an account that already exists,
  because the seed leaves such an account untouched and any password shown
  here would not work.

The closing Login block repeats it in the form you act on — for example Admin admin@example.org / existing password (unchanged) — and, when only one of the two bootstrap accounts already existed, still prints the freshly generated password for the other one.

What to do, in order of preference:

1. Sign in with the credentials that database was originally set up with. They still work; nothing changed them.

2. If they are lost, replace one account’s password. See Reset a password:

   npx -y seqdesk@latest reset-password admin@example.org --dir "$HOME/seqdesk"

3. If you actually wanted a clean instance, install against a different database — a new --database-url, or a different SEQDESK_PG_HOME so the installer creates a fresh cluster it owns.

Two related messages mean something narrower:

• This database already held N user account(s) before this install. — the database had users, but none at a bootstrap address, so this install created its own account alongside them. Nothing existing was changed.
• Unverified: this install could not check whether the database already had SeqDesk accounts. — the pre-install probe failed. The credentials printed are the ones this install generated; if the database already held those accounts, they were left alone and the printed values do not open it.

Answering Backup and replace? at the prompt (or passing --overwrite-existing) never touches the database. It moves <dir> to <dir>.backup.<timestamp> and nothing else — no database is backed up, dropped or reset, and existing accounts keep their passwords.

SeqDesk manages its own PostgreSQL

You usually do not have to provide a database. When you pass no --database-url, the installer works down a ladder: it reuses a healthy server on the configured connection; then a healthy local Unix socket it can administer; on macOS it starts an already-registered but idle Homebrew service; and otherwise it creates its own cluster.

That private cluster lives in ${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres} (data/, socket/, and server.log) and is socket-only: listen_addresses is empty, pg_hba.conf rejects every host and hostssl line, and no TCP port is opened, so pg_isready -h 127.0.0.1 will never answer for it. Point pg_isready and psql at the socket directory instead, which is why the generated URL carries a host=<socket dir> parameter. Your operating-system account is the cluster superuser through peer authentication.

The cluster is deliberately not registered with launchd or systemd. Instead, start.sh in the installation directory checks pg_ctl status and starts the cluster before launching the app, so the database returns after a reboot together with the SeqDesk process. Startup failures are reported by that wrapper and logged to the cluster’s server.log.

Set SEQDESK_PG_HOME to relocate the cluster and keep it short. The installer’s length check is on the socket directory it creates inside it, $SEQDESK_PG_HOME/socket, which must be 85 characters or fewer — so SEQDESK_PG_HOME itself has a 78-character budget. Re-running the installer never rebuilds an initialized cluster, and the cluster must be created by your normal login user, never with sudo.

A local socket owned by a different account is skipped with a warning rather than treated as an error: SeqDesk declines to send generated credentials to a server it does not own, then continues down the ladder and normally ends up creating its own cluster. No action is required.

Because the cluster has no TCP listener, seqdesk doctor — whose database check is a TCP connect to the host and port in databaseUrl — reports PostgreSQL TCP: localhost:5432 unreachable and exits 1 on a perfectly healthy install. Check the cluster directly instead:

PGROOT="${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres}"
pg_ctl -D "$PGROOT/data" status
pg_isready -h "$PGROOT/socket"

An explicit --database-url or SEQDESK_DATABASE_URL is never silently retargeted. When that endpoint is unreachable, macOS reports it and stops while Linux defers to the existing system setup. PostgreSQL 14+ is enforced when a socket is adopted, and SQLite is rejected.

Miniconda says the prefix already exists

This usually means a Conda directory exists but its executable is not on PATH. Check the base without changing or deleting it:

"$HOME/miniconda3/bin/conda" --version
"$HOME/miniconda3/condabin/conda" --version

Only one command needs to succeed. The current installer checks an explicitly configured base (SEQDESK_EXEC_CONDA_PATH) first, then a working conda on PATH, then an executable CONDA_EXE, and finally these standard user bases in order: ~/miniconda3, ~/seqdesk-miniconda3, ~/miniforge3, ~/mambaforge, ~/anaconda3. A working base is reused and saved in the SeqDesk pipeline settings even when it was not on PATH.

If ~/miniconda3 exists but is not a working Conda base, SeqDesk leaves it untouched and installs into the unused fallback ~/seqdesk-miniconda3. If both locations already exist but are unusable, the installer stops before downloading SeqDesk and prints a fresh path to use. It never deletes, overwrites, or performs an in-place Miniconda update.

SEQDESK_EXEC_CONDA_PATH is authoritative. Point it either to a working Conda base containing bin/conda or condabin/conda, or to a path that does not yet exist:

SEQDESK_EXEC_CONDA_PATH="$HOME/miniconda3" \
  seqdesk --interactive --dir "$HOME/seqdesk"
 
# If that base is incomplete, choose a new unused path instead:
SEQDESK_EXEC_CONDA_PATH="$HOME/seqdesk-miniconda3-new" \
  seqdesk --interactive --dir "$HOME/seqdesk"

An explicitly selected path that already exists but is unusable causes an actionable stop; SeqDesk does not silently redirect an operator-provided path. If Miniconda starts and then fails, it may leave a partial directory at the new target. Reuse that directory only when its bin/conda or condabin/conda command succeeds; otherwise choose another unused path. Use --without-pipelines when this host only needs the core application.

Collect a useful diagnostic

For a completed host installation, run the read-only checker against the installation root:

seqdesk doctor --dir "$HOME/seqdesk" --url http://127.0.0.1:8000

For an installer failure, re-run with --verbose (or SEQDESK_VERBOSE=1) to promote the installer’s diagnostic narration from the log to the terminal, and inspect the most recent log:

ls -1t /tmp/seqdesk-install-*.log | head -n 1
tail -n 120 /tmp/seqdesk-install-YYYYMMDD-HHMMSS.log

Replace the example log filename with the path printed by the first command. The default location is /tmp/seqdesk-install-<timestamp>.log; if you set SEQDESK_LOG, read that file instead. The seqdesk doctor reference lists every check and exit code.

Proxy and firewall checklist

The installer needs outbound DNS and HTTPS (TCP 443) to:

• registry.npmjs.org for the launcher, runtime dependencies and optional PM2;
• seqdesk.org/install.sh and seqdesk.org/api/version;
• the exact release downloadUrl returned by the version API; and
• when pipelines are enabled, repo.anaconda.com and conda.anaconda.org (Conda Forge/Bioconda), plus any private pipeline package URL configured by your install profile.

The running app needs outbound access to a PostgreSQL host and port (normally TCP 5432) only when you supplied a remote --database-url. A default install reaches PostgreSQL over a local Unix socket — the SeqDesk-owned cluster opens no TCP port at all — so no firewall or egress rule is involved. For remote users, allow inbound HTTPS to your reverse proxy and proxy it to 127.0.0.1:8000; the SeqDesk port itself does not need to be public when the proxy is on the same host. Note that SeqDesk binds 0.0.0.0 by default, so the app port is reachable on every interface until you set SEQDESK_BIND_HOST=127.0.0.1 at install or start time; set it, or add a host firewall rule, when only the reverse proxy should reach it. Set --nextauth-url to the public HTTPS origin and preserve the original Host and X-Forwarded-Proto headers at the proxy.

Before retrying, test from the SeqDesk service account and host:

curl -fsSI https://seqdesk.org/install.sh
curl -fsS https://seqdesk.org/api/version >/dev/null
npm ping
 
# Remote or TCP database only:
pg_isready -h <database-host> -p 5432
 
# SeqDesk-managed or socket-based install (no TCP listener):
pg_isready -h "${SEQDESK_PG_HOME:-$HOME/.seqdesk/postgres}/socket"

Export your organization’s HTTPS_PROXY, HTTP_PROXY, and an appropriate NO_PROXY before running the launcher when an egress proxy is required. If TLS inspection is in use, install the organization’s CA in the operating system, Node/npm and Conda trust stores. Do not work around certificate errors with curl -k, NODE_TLS_REJECT_UNAUTHORIZED=0, or npm strict-ssl=false; ask the network administrator to allow the endpoint or fix the trust chain instead.

Know when to involve an administrator

Ask the host or database administrator when:

• your account cannot create the intended service directory;
• a pre-existing system PostgreSQL must be administered, or the PostgreSQL server package must be installed on Linux — both need root or passwordless sudo. SeqDesk’s own cluster needs no privileged change, and on macOS PostgreSQL setup always runs as your normal login user, never with sudo;
• pg_hba.conf, TLS, DNS, or firewall policy blocks the configured database;
• the service needs a trusted-network route, reverse proxy, or TLS certificate;
• sequencing, reference-database, pipeline-work, or backup storage must be provisioned; or
• Slurm clients, shared paths, identities, and compute-node access are not already working from the SeqDesk host.

SeqDesk should run as a non-root service account after those prerequisites are prepared.