Troubleshooting

Common issues and solutions for Zipline

This guide covers common issues you may encounter while running Zipline and how to resolve them.

Getting Help

Before diving into troubleshooting:

1. Check the Zipline logs for error messages
2. Search existing GitHub issues
3. Join the Discord server for community support
4. Review relevant configuration in this documentation

Checking Logs

Docker Deployment

# View recent logs
docker compose logs zipline

# Follow logs in real-time
docker compose logs -f zipline

# View last 100 lines
docker compose logs --tail 100 zipline

# View database logs
docker compose logs postgresql

Source Deployment

# If running with systemd
sudo journalctl -u zipline -f

# If running directly
# Check stdout/stderr or log files in your deployment

Enable Debug Logging

For more detailed logs, set the DEBUG environment variable:

DEBUG=zipline*

This enables verbose logging for all Zipline components.

Installation & Startup Issues

Zipline exits immediately on startup

Common causes:

1. Missing CORE_SECRET

   Error: CORE_SECRET is required
   

   Solution: Generate and set CORE_SECRET:

   echo "CORE_SECRET=$(openssl rand -base64 42 | tr -dc A-Za-z0-9 | cut -c -32)" >> .env
   

2. Database connection failed

   Error: connect ECONNREFUSED 127.0.0.1:5432
   

   Solution:

   • Verify PostgreSQL is running: docker compose ps
   • Check DATABASE_URL is correct
   • Wait for database to be ready (use healthcheck in docker-compose)

3. S3 access test failed

   there was an error while testing write access
   zipline will now exit
   

   Solution: Check S3 configuration:

   • Verify credentials are correct
   • Ensure bucket exists and is accessible
   • Check bucket permissions (see S3 Setup)

Cannot connect to database

Error messages:

Error: P1001: Can't reach database server
Error: password authentication failed for user

Solutions:

1. Verify database is running:

   docker compose ps postgresql
   

2. Check DATABASE_URL format:

   # Correct format
   DATABASE_URL=postgres://username:password@host:5432/database
   

3. Check password special characters: Passwords with special characters may need URL encoding:

   # If password contains @, #, etc.
   # Encode it: https://www.urlencoder.org/
   

4. Wait for database to be ready: Docker compose should have healthcheck:

   depends_on:
     postgresql:
       condition: service_healthy
   

Port already in use

Error:

Error: listen EADDRINUSE: address already in use :::3000

Solutions:

1. Change Zipline port:

   CORE_PORT=3001
   

2. Find and stop process using port:

   # Find process
   sudo lsof -i :3000
   # or
   sudo netstat -tlnp | grep 3000
   
   # Stop process
   sudo kill -9 <PID>
   

3. Change Docker port mapping:

   ports:
     - '3001:3000'  # External:Internal
   

Docker compose fails to start

Common issues:

1. Missing environment variables:

   Error: variable is not set: POSTGRESQL_PASSWORD
   

   Solution: Create .env file with required variables

2. Invalid docker-compose.yml:

   # Validate syntax
   docker compose config
   

3. Volume permission issues:

   # Fix permissions
   sudo chown -R $USER:$USER ./uploads ./public ./themes
   

Upload Issues

File uploads fail or return errors

Error types:

1. 413 Payload Too Large

   • File exceeds FILES_MAX_FILE_SIZE limit
   • Reverse proxy has lower limit

   Solution:

   # Zipline
   FILES_MAX_FILE_SIZE=500mb
   
   # Nginx
   client_max_body_size 500M;
   

2. 408 Request Timeout

   • Upload taking too long
   • Network issues

   Solution: Increase timeouts in reverse proxy:

   proxy_connect_timeout 600;
   proxy_send_timeout 600;
   proxy_read_timeout 600;
   

3. 401 Unauthorized

   • Invalid or missing API token
   • Token revoked or expired

   Solution:

   • Generate new token in user settings
   • Update ShareX/client configuration

4. Storage write failed

   • Disk full (local storage)
   • S3 permissions issue

   Solution:

   # Check disk space
   df -h
   
   # For S3, verify permissions
   # See S3 Setup guide
   

Uploads succeed but files return 404

Common causes:

1. Files not in correct location:

   # Verify file exists
   ls -la ./uploads/
   # For S3
   aws s3 ls s3://your-bucket/
   

2. Incorrect datasource configuration:

   # Check datasource type matches actual storage
   # If using S3, must have DATASOURCE_TYPE=s3
   

3. File permissions (local storage):

   # Ensure Zipline can read files
   sudo chown -R zipline:zipline ./uploads
   # or if running as current user
   sudo chown -R $USER:$USER ./uploads
   

4. S3 bucket/subdirectory mismatch:

   • Verify DATASOURCE_S3_BUCKET matches actual bucket
   • Check DATASOURCE_S3_SUBDIRECTORY if used

Chunked/partial uploads fail

Error:

Error: Chunk upload failed

Solutions:

1. Check chunk configuration:

   CHUNKS_ENABLED=true
   CHUNKS_SIZE=25mb
   CHUNKS_MAX=95mb
   

2. Verify temp directory is writable:

   # Default: OS temp directory
   # Custom:
   CORE_TEMP_DIRECTORY=/path/to/temp
   

3. Increase reverse proxy limits: Must accommodate chunk size + overhead

Image compression not working

Check:

1. Feature is enabled:

   FEATURES_IMAGE_COMPRESSION=true
   

2. Compression format is set:

   FILES_DEFAULT_COMPRESSION_FORMAT=jpg
   # or webp, png
   

3. Check logs for compression errors:

   docker compose logs zipline | grep compression
   

Authentication & Users

Cannot log in / wrong password

Solutions:

1. Reset password via CLI:

   docker exec -it zipline pnpm ctl user reset-password <username>
   

2. Verify user exists:

   docker exec -it zipline pnpm ctl user list
   

3. Check for special characters in password:

   • Avoid special characters that might be interpreted by shell
   • Use strong alphanumeric passwords

OAuth login fails

Common issues:

1. Redirect URI mismatch:

   • OAuth provider redirect URI must match exactly
   • Include https://your-domain.com/api/auth/oauth/<provider>/callback

2. Missing OAuth configuration:

   # Discord example
   OAUTH_DISCORD_CLIENT_ID=your_client_id
   OAUTH_DISCORD_CLIENT_SECRET=your_secret
   OAUTH_DISCORD_REDIRECT_URI=https://your-domain.com/api/auth/oauth/discord/callback
   

3. OAuth provider credentials invalid:

   • Verify client ID and secret are correct
   • Check if OAuth app is enabled in provider dashboard

2FA/TOTP not working

Solutions:

1. Check TOTP is enabled:

   MFA_TOTP_ENABLED=true
   MFA_TOTP_ISSUER=Zipline
   

2. Time synchronization:

   • TOTP requires accurate system time
   • Sync server time: sudo ntpdate -s time.nist.gov

3. Regenerate TOTP secret:

   • Disable and re-enable 2FA in user settings
   • Scan new QR code

User registration not working

Check feature flag:

FEATURES_USER_REGISTRATION=true
# For OAuth registration
FEATURES_OAUTH_REGISTRATION=true

Invites:

• If registration is disabled, users need invites
• Generate invite in admin panel

Performance Issues

Slow file uploads/downloads

Possible causes:

1. Network bottleneck:

   • Check bandwidth between client and server
   • Use iperf3 to test network speed

2. Disk I/O bottleneck (local storage):

   # Test disk speed
   sudo hdparm -t /dev/sda
   # or
   dd if=/dev/zero of=test bs=1M count=1000
   

3. S3 performance:

   • Choose region close to users
   • Consider CloudFront or CDN
   • Check S3 connection pooling is working (max 1000 connections)

4. Reverse proxy not using keep-alive:

   # Nginx
   proxy_http_version 1.1;
   proxy_set_header Connection "";
   

High memory usage

Solutions:

1. Limit thumbnail generation threads:

   FEATURES_THUMBNAILS_NUM_THREADS=2
   

2. Disable metrics if not needed:

   FEATURES_METRICS_ENABLED=false
   

3. Reduce chunk size:

   CHUNKS_SIZE=10mb
   

4. Monitor with Docker stats:

   docker stats zipline
   

Database growing too large

Solutions:

1. Disable metrics collection:

   FEATURES_METRICS_ENABLED=false
   

2. Clean old metrics:

   -- Connect to database
   DELETE FROM "Metric" WHERE "createdAt" < NOW() - INTERVAL '30 days';
   

3. Vacuum database:

   docker exec zipline-postgresql vacuumdb -U zipline -d zipline --full
   

Storage Issues

S3 connection errors

Error types:

1. Connection timeout:

   • Check network connectivity to S3 endpoint
   • Verify endpoint URL is correct
   • Check firewall allows HTTPS to S3

2. Access denied:

   • Verify IAM permissions (see S3 Setup)
   • Check bucket policy
   • Ensure credentials are valid

3. Bucket not found:

   • Verify bucket name is correct
   • Check region matches bucket region
   • For path-style: ensure DATASOURCE_S3_FORCE_PATH_STYLE=true

Local storage disk full

Solutions:

1. Check disk usage:

   df -h
   du -sh ./uploads
   

2. Clean up old files:

   • Delete expired files manually
   • Ensure deletion task is running:
     TASKS_DELETE_INTERVAL=30m
     

3. Migrate to S3:

   • See S3 Setup guide
   • Transfer existing files to S3

Thumbnails not generating

Check:

1. Feature is enabled:

   FEATURES_THUMBNAILS_ENABLED=true
   

2. Thumbnail interval:

   TASKS_THUMBNAILS_INTERVAL=30m
   

3. Check logs for errors:

   docker compose logs zipline | grep thumbnail
   

4. Supported formats:

   • Images: JPEG, PNG, WebP, GIF
   • Videos: MP4, WebM, MOV (requires ffmpeg)

Reverse Proxy Issues

502 Bad Gateway

Causes:

1. Zipline not running:

   docker compose ps zipline
   # Should show "Up"
   

2. Wrong proxy_pass address:

   # Should match Zipline's bind address
   proxy_pass http://localhost:3000;
   

3. Firewall blocking connection:

   # Allow local connections
   sudo ufw allow from 127.0.0.1
   

Client IP shows as proxy IP

Solution:

# Enable trust proxy
CORE_TRUST_PROXY=true

And ensure proxy sends headers:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Infinite redirect loop

Common with Cloudflare:

1. Set SSL mode to Full:

   • Cloudflare Dashboard → SSL/TLS → Full or Full (strict)

2. Check HTTPS configuration:

   CORE_RETURN_HTTPS_URLS=true
   

3. Verify reverse proxy doesn’t force redirect:

   • Remove HTTP to HTTPS redirects if Cloudflare handles it

Miscellaneous

ShareX configuration not working

Common issues:

1. Wrong API endpoint:

   URL: https://your-domain.com/api/upload
   

2. Missing or wrong authorization:

   Header: Authorization
   Value: YOUR_API_TOKEN
   

3. File form field name:

   File form name: file
   

4. Response URL parsing:

   URL: $json:url$
   

Custom domain not working

Checklist:

• DNS A/AAAA record points to server
• Domain added to DOMAINS or admin dashboard
• Reverse proxy accepts domain
• SSL certificate covers domain
• CORE_TRUST_PROXY=true if behind proxy

See Custom Domains guide for details.

Webhooks not firing

Check:

1. Webhook URL is configured:

   # Discord
   DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
   # HTTP
   HTTP_WEBHOOK_ON_UPLOAD=https://your-webhook.com/endpoint
   

2. Check logs for webhook errors:

   docker compose logs zipline | grep webhook
   

3. Verify webhook endpoint is reachable:

   curl -X POST https://your-webhook.com/endpoint
   

Database migrations fail

Error:

Error: Migration failed

Solutions:

1. Check database connection:

   • Ensure database is accessible
   • Verify credentials

2. Manual migration:

   docker exec zipline pnpm prisma migrate deploy
   

3. Reset database (development only):

   docker exec zipline pnpm prisma migrate reset
   
   This deletes all data. Only use in development!

Getting More Help

If you’re still experiencing issues:

1. Gather information:

   • Zipline version: Check GitHub release or Docker image tag
   • Deployment method: Docker, source, etc.
   • Configuration: Relevant environment variables (redact secrets)
   • Error logs: Recent error messages
   • Steps to reproduce: What triggers the issue

2. Search existing issues:

   • GitHub Issues
   • Use search with error messages or keywords

3. Ask for help:

   • Discord server - Community support
   • GitHub Discussions - Questions and ideas
   • GitHub Issues - Bug reports

4. Provide context: Include:

   • Description of the issue
   • What you’ve already tried
   • Relevant configuration (redacted)
   • Error logs
   • Environment details (OS, Docker version, etc.)

When asking for help, use code blocks for logs and configuration. This makes it easier to read and helps others assist you faster.

Common Error Messages

Error Message	Likely Cause	Solution
CORE_SECRET is required	Missing secret	Generate and set CORE_SECRET in .env
connect ECONNREFUSED	Database not accessible	Check DATABASE_URL and database status
error while testing write access	S3 permissions issue	Verify S3 credentials and bucket permissions
listen EADDRINUSE	Port already in use	Change CORE_PORT or stop conflicting process
Unauthorized	Invalid API token	Generate new token in user settings
Payload Too Large	File size limit	Increase FILES_MAX_FILE_SIZE and proxy limits
Migration failed	Database migration issue	Check database connection, run migrations manually
ENOSPC: no space left	Disk full	Clean up files or increase disk space

For security issues, please report via GitHub Security Advisories instead of public issues or Discord.