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

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; the path must be 85 characters or shorter (the macOS Unix-socket limit) or the installer stops and asks for a shorter one. Re-running the installer never rebuilds an initialized cluster, and the cluster must be created by your normal login user, never with sudo.

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 first, then a working conda on PATH, followed by standard user bases including ~/miniconda3, ~/seqdesk-miniconda3, ~/miniforge3, ~/mambaforge, and ~/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.