← All articles

How to view startup errors

Before diving into specific errors, know where to look:

# If running as a systemd service
journalctl -u paperclip -n 50 --no-pager

# If running directly
npx paperclipai server start
# Errors appear in the terminal output

# Docker
docker logs paperclip
docker compose logs paperclip

Error: Port already in use

Error: listen EADDRINUSE: address already in use 127.0.0.1:3100

Cause: Something else is running on port 3100.

Fix: Find and stop whatever is using port 3100:

# Find what's using the port
sudo lsof -i :3100
sudo ss -tlnp | grep 3100

# Kill it (replace PID with the process ID from above)
sudo kill -9 PID

Or change Paperclip's port:

PAPERCLIP_LISTEN_PORT=3200 npx paperclipai server start

Error: Missing BETTER_AUTH_SECRET

Error: BETTER_AUTH_SECRET is required but not set

or:

Fatal: authentication secret is missing or too short

Cause: BETTER_AUTH_SECRET isn't set or is too short.

Fix:

# Generate a strong secret
openssl rand -hex 32

# Add it to your .env file
echo "BETTER_AUTH_SECRET=your_generated_value_here" >> .env

# Or export it directly
export BETTER_AUTH_SECRET=$(openssl rand -hex 32)

Error: Database migration failed

Error: Database migration failed: SQLITE_CANTOPEN: unable to open database file

or:

Error: ENOENT: no such file or directory, open '/opt/paperclip/data/paperclip.db'

Cause: Paperclip can't write to the data directory — it either doesn't exist or the process doesn't have write permission.

Fix:

# Create the directory
mkdir -p /opt/paperclip/data

# Check ownership (should match the user running Paperclip)
ls -la /opt/paperclip/

# Fix ownership
sudo chown -R deploy:deploy /opt/paperclip/data

# Verify the current user can write
touch /opt/paperclip/data/test && rm /opt/paperclip/data/test
echo "Write access OK"

Error: Wrong Node.js version

Error: The engine "node" is incompatible with this module.
Expected version ">=18.0.0". Got "16.x.x"

Cause: Paperclip requires Node.js 18+.

Fix:

# Check current version
node --version

# Install Node 20 LTS via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Verify
node --version  # v20.x.x

Error: Secrets provider can't read master key

Error: Secrets provider error: master key file not found at /opt/paperclip/secrets/master.key

Cause: The secrets encryption master key file is missing. This happens when PAPERCLIP_SECRETS_STRICT_MODE=true and the key file doesn't exist yet (first run) or was deleted.

Fix for first run: Paperclip creates the key file automatically on first start. If PAPERCLIP_DATA_DIR is set correctly and the directory is writable, this resolves itself.

Fix for missing key (not first run): If you deleted or lost the key file, agent secrets are unrecoverable — they were encrypted with that key. You'll need to reconfigure agent API keys after recreating the key file:

# Generate a new master key
openssl rand -hex 32 > /opt/paperclip/secrets/master.key
chmod 600 /opt/paperclip/secrets/master.key

# Then restart Paperclip and re-enter agent API keys

Error: Module not found

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'paperclipai'

Cause: Paperclip isn't installed, or the npx prefix is missing when using a local install.

Fix:

# Install globally
npm install -g paperclipai

# Verify
which paperclipai
paperclipai --version

# Or use npx explicitly
npx paperclipai@latest server start

Error: EACCES permissions denied

Error: EACCES: permission denied, mkdir '/root/.paperclip'

Cause: Paperclip is trying to write to a directory owned by a different user.

Fix: Run Paperclip as the correct user (not root), or set PAPERCLIP_DATA_DIR to a directory the running user owns:

# Bad: running as root
sudo npx paperclipai server start

# Good: running as deploy user
su - deploy
npx paperclipai server start

# Or set data dir explicitly
PAPERCLIP_DATA_DIR=/home/deploy/paperclip-data npx paperclipai server start

Error: Bootstrap not ready

Error: Server not accepting connections — bootstrap status is not ready

Cause: Paperclip is starting but hasn't finished its bootstrap process (first-run initialization). This is usually temporary.

Fix: Wait 30–60 seconds and try again. On first boot, Paperclip runs database migrations and sets up the initial state. If it's still failing after 2 minutes, check disk space and write permissions:

df -h
ls -la $PAPERCLIP_DATA_DIR

General debugging checklist

If none of the above match your error:

1. Check full logs: journalctl -u paperclip -n 100
2. Verify environment: cat /opt/paperclip/.env and confirm all required vars are set
3. Check disk space: df -h — a full disk causes cryptic errors
4. Check Node version: node --version — must be 18+
5. Check file permissions: ls -la /opt/paperclip/
6. Try running manually: Stop the service and run npx paperclipai server start directly to see errors in real time

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.