Loading...

Knowledge Base
Home 
 
/
 Self-Managed VPS - How to Fix the Paperclip Dashboard Black Page Issue on Ubuntu 24.04
Categories: VPS, Applications

Self-Managed VPS - How to Fix the Paperclip Dashboard Black Page Issue on Ubuntu 24.04

If you have installed the Paperclip AI coding assistant on Ubuntu 24.04 in your Self-Managed VPS but encounter a black page when accessing its web UI at http://<server-ip>:3100, this article will guide you through diagnosing and fixing the issue.

Symptoms

  • When opening the Paperclip dashboard URL, only a black page is displayed.
  • The browser console shows WebSocket connection errors to ws://0.0.0.0:13100.
  • No critical errors found in Paperclip service logs. You can verify this by running: 
    journalctl -u paperclip -n 100 --no-pager
    Example Output:
    -- Logs begin at Thu 2026-04-29 15:00:00 UTC, end at Thu 2026-04-30 20:00:00 UTC
Apr 30 18:15:01 server systemd[1]: Started paperclip.service - Paperclip.
  • Paperclip service appears active and running. You can check its status with: 
    systemctl status paperclip
    Example Output:
    ● paperclip.service - Paperclip
     Loaded: loaded (/etc/systemd/system/paperclip.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-04-30 18:15:01 UTC; 2h 30min ago
   Main PID: 983 (node)
      Tasks: 217 (limit: 9500)
     Memory: 1.1G

Root Cause

This black page usually happens when the Paperclip frontend tries to create a WebSocket connection to 0.0.0.0, which is not a valid client connection. This means that there was a problem with the server network settings, particularly the Bind host and Public base URL parameters.

Step-by-Step Resolution

1. Verify the Paperclip Service Status

Ensure the Paperclip backend service is running by executing:

systemctl status paperclip

2. Check Service Logs

Look for any startup or runtime errors:

journalctl -u paperclip -n 100 --no-pager

If no major errors are present, proceed to configuration.

3. Run the Paperclip Interactive Configuration

Start the interactive configuration tool:

sudo -u paperclip env HOME=/opt/paperclip bash -c "cd /opt/paperclip/app && pnpm paperclipai configure"

Select the following options when prompted:

  • Section to configure: Server
  • Reachability: Custom
  • Server port: 3100
  • Auth mode: Authenticated
  • Exposure profile: Public internet
  • Bind host: Your server's IP address (e.g., 123.1.2.345)
  • Public base URL: http://<server-ip>:3100 (e.g., http://123.1.2.345:3100)

Complete the configuration and save changes.

4. Restart the Paperclip Service

Apply the new configuration by restarting the service:

systemctl restart paperclip

5. Clear Browser Cache and Reload

To avoid any cached errors, clear your browser cache or open the UI in an incognito/private window and access:

http://<server-ip>:3100

6. Bootstrap the First Admin Account

If you see a message stating no admin exists, create the first CEO admin user with:

sudo -u paperclip env HOME=/opt/paperclip bash -c "cd /opt/paperclip/app && pnpm paperclipai auth bootstrap-ceo"
Example Output:
Invite URL: http://123.1.2.345:3100/auth/invite?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Open the invite URL in your browser to complete admin setup.

Summary

The black page happens due to WebSocket connections pointing to 0.0.0.0 caused by default or incorrect Paperclip network configurations. Correctly setting the server bind host and public base URL in Paperclip’s configuration solves the issue, allowing the frontend to load properly and the dashboard to become accessible.

If you continue to face issues, checking browser console logs and Paperclip service logs helps identify further problems.

Loading...