Skip to main content
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

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)
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
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
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

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
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
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
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

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
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
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
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

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 "";
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
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

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
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:
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

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
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;
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

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$
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.
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
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:
  3. Ask for help:
  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 MessageLikely CauseSolution
CORE_SECRET is requiredMissing secretGenerate and set CORE_SECRET in .env
connect ECONNREFUSEDDatabase not accessibleCheck DATABASE_URL and database status
error while testing write accessS3 permissions issueVerify S3 credentials and bucket permissions
listen EADDRINUSEPort already in useChange CORE_PORT or stop conflicting process
UnauthorizedInvalid API tokenGenerate new token in user settings
Payload Too LargeFile size limitIncrease FILES_MAX_FILE_SIZE and proxy limits
Migration failedDatabase migration issueCheck database connection, run migrations manually
ENOSPC: no space leftDisk fullClean up files or increase disk space
For security issues, please report via GitHub Security Advisories instead of public issues or Discord.

Build docs developers (and LLMs) love

Get started for freeTalk to us