Troubleshooting & Operational Diagnostics

This guide addresses common error states and operational problems encountered during deployment and daily operation.

Inspecting Logs

Start by reviewing container logs for error entries:

# Follow latest container logs
docker compose logs -f cubycloud

# Filter specifically for errors or warnings
docker compose logs cubycloud | grep -E "ERROR|WARN"

Common Symptoms and Fixes

1. Storage Node Offline or Inactive

• Symptom: Files appear marked with an Offline badge in the drive, or uploads fail with Storage node unavailable.
• Cause: CubyCrate runs a storage node probe every 3 seconds. If a physical disk mount is missing, unmounted, or an S3 bucket is unreachable, the node is marked offline to prevent incomplete writes.
• Fix:
  • For local disks: Ensure the host storage path is mounted into the container and has read/write permissions.
  • For S3 nodes: Verify your bucket endpoint, network egress, and IAM credentials. Check if your S3 provider requires path-style addressing.

2. Uploads Fail on Large Files (HTTP 413 or Timed Out)

• Symptom: Small files upload immediately, but files above a certain size fail with 413 Request Entity Too Large or connection timeouts.
• Cause: The upstream reverse proxy (Nginx or Caddy) has a default body size limit or proxy timeout that cuts off long-running uploads.
• Fix:
  • In Nginx, set client_max_body_size 10G; and increase proxy_read_timeout 600s;.
  • In Caddy, configure request_body { max_size 10GB }.
  • Ensure the temporary chunk path /app/data/temp/ has adequate free disk space to store inflight TUS chunks.

3. Real-Time File Updates Not Appearing (SSE Disconnected)

• Symptom: Changes made by colleagues (such as new uploads in the Organization folder) do not reflect automatically without a manual page refresh.
• Cause: The reverse proxy is buffering responses from the Server-Sent Events endpoint at /api/v1/events.
• Fix:
  • In Nginx, ensure buffering is disabled for the SSE route:

    location /api/v1/events {
        proxy_pass http://127.0.0.1:8383;
        proxy_buffering off;
        proxy_cache off;
    }

  • In Caddy, set flush_interval -1 on the reverse proxy handler for @sse.

4. Database Busy or Locked Errors (SQLITE_BUSY)

• Symptom: Server logs show database is locked or SQLITE_BUSY.
• Cause: SQLite runs in WAL (Write-Ahead Logging) mode and expects a single active writer connection pool (MaxOpenConns=1). Mounting /app/data over network-attached filesystems (such as NFS or SMB) can break SQLite POSIX advisory locking.
• Fix:
  • Always store cubycloud.db on a local host filesystem (ext4, XFS, APFS), never directly over network mounts like NFS or CIFS.

5. Setup Wizard Keeps Prompting (/setup)

• Symptom: Accessing the website always redirects to /setup instead of the login page.
• Cause: The initial setup wizard has not finished writing the administrator account and storage node configuration to the database, or file permissions prevented creating cubycloud.db.
• Fix:
  • Verify that the directory permissions on /app/data allow the container process to write files.
  • Complete all 5 steps of the setup wizard and confirm the final submission.

6. Lost Administrator Password

• Symptom: The administrator cannot sign in and email recovery is not configured.
• Cause: Forgotten password or locked account.
• Fix:
  • Use the 32-character Crockford Base32 recovery key generated during the initial setup wizard.
  • Navigate to /login, select Forgot password / Reset with recovery key, and enter your recovery key to define a new administrator password.

Next Steps

• Backup and Recovery: Protect database and secret keys before performing maintenance.
• Configuration Guide: Review reverse proxy templates and environment variables.