This guide covers common issues you may encounter with your self-hosted eCommerce Builder and how to resolve them.
\r\nApplication Issues
\r\nProblem: Application Won't Start
\r\nIf the systemd service fails to start or immediately stops:
\r\nCheck the logs to see what error occurred: sudo journalctl -u ebuilder -n 100
\r\nCommon causes include:
\r\nPort already in use. Check what is using it: sudo lsof -i :8000. Stop the conflicting application or change the port in your systemd service file and Caddyfile.
\r\nInvalid environment variables. Review your .env file for syntax errors, missing quotes, or invalid values.
\r\nPermissions issues. Ensure the data directory is writable by the user running the service: sudo chown -R youruser:youruser data/
\r\nTry reinstalling dependencies from scratch: source venv/bin/activate, then pip install -r requirements.txt --no-cache-dir, then sudo systemctl restart ebuilder
\r\nProblem: Application Keeps Restarting
\r\nIf sudo systemctl status ebuilder shows the service repeatedly failing:
\r\nCheck the logs for the specific error: sudo journalctl -u ebuilder -n 100
\r\nLook for errors about missing environment variables, database connection failures, or Python import errors.
\r\nCommon causes include a corrupted database, a missing required environment variable in .env, or insufficient memory.
\r\nIf the database is suspected, restore from your most recent backup.
\r\n\r\n
Static Files and CSS Issues
\r\nProblem: Site Loads But Has No Styling
\r\nIf your site appears as plain HTML with no CSS styling:
\r\nThe static files may not have been collected. Run: source venv/bin/activate then python manage.py collectstatic --no-input
\r\nThen restart the service: sudo systemctl restart ebuilder
\r\nCheck your browser's developer console (F12) for 404 errors loading CSS files.
\r\nVerify WhiteNoise is properly configured in settings.py (it should be in the default installation).
\r\nTry a hard refresh in your browser: Ctrl+Shift+R on Windows/Linux or Cmd+Shift+R on Mac.
\r\nClear your browser cache completely and try again.
\r\nProblem: Admin Panel Styling Broken
\r\nIf the admin interface appears unstyled:
\r\nVerify Adminita is installed: source venv/bin/activate then pip show adminita
\r\nRun collectstatic again: python manage.py collectstatic --no-input
\r\nCheck that STATIC_ROOT is configured correctly in settings.py.
\r\nRestart the service: sudo systemctl restart ebuilder
\r\nProblem: Images Not Displaying
\r\nIf product images or uploaded files do not display:
\r\nCheck that the media directory has correct permissions: ls -la data/media. It should be writable by the user running the service.
\r\nVerify the image file actually exists in data/media/products or the appropriate subdirectory.
\r\nCheck your MEDIA_URL and MEDIA_ROOT settings in settings.py.
\r\nEnsure Caddy is properly proxying requests to your application without blocking media files.
\r\n\r\n
Database Issues
\r\nProblem: Database Locked Errors
\r\nIf you see \"database is locked\" errors:
\r\nThis occurs when multiple processes try to write to SQLite simultaneously.
\r\nCheck that only one instance of the application is running: ps aux | grep gunicorn
\r\nRestart the service: sudo systemctl restart ebuilder
\r\nIf the problem persists frequently, consider migrating to PostgreSQL for better concurrency handling.
\r\nProblem: Cannot Access Admin After Password Change
\r\nIf you have forgotten your admin password or cannot log in:
\r\nReset the password using the Django management command: source venv/bin/activate then python manage.py changepassword your@email.com
\r\nEnter a new password when prompted.
\r\nIf you have forgotten your email address, list all superusers: python manage.py shell, then type: from accounts.models import User; print(list(User.objects.filter(is_superuser=True).values_list('email', flat=True)))
\r\nType exit() to leave the shell.
\r\nProblem: Database Corruption
\r\nIf you suspect database corruption:
\r\nCheck database integrity: python manage.py dbshell, then run: PRAGMA integrity_check;
\r\nIf the result is not \"ok\", your database is corrupted.
\r\nStop the application immediately: sudo systemctl stop ebuilder
\r\nRestore from your most recent backup: python manage.py loaddata backup.json
\r\nIf you have no backup, try running: PRAGMA wal_checkpoint(TRUNCATE); in the database shell, but data loss may occur.
\r\nAlways maintain regular backups to prevent permanent data loss.
\r\n\r\n
Payment and Stripe Issues
\r\nProblem: Payments Fail Immediately
\r\nIf customers see an error when trying to pay:
\r\nVerify your Stripe keys are correct in .env: STRIPE_PUBLIC_KEY and STRIPE_SECRET_KEY
\r\nEnsure you are using keys from the correct mode (test keys for testing, live keys for production).
\r\nCheck that your keys start with the correct prefix: pk_live or pk_test for public keys, sk_live or sk_test for secret keys.
\r\nRestart the application after any .env changes: sudo systemctl restart ebuilder
\r\nTest with Stripe test card 4242 4242 4242 4242 if in test mode.
\r\nCheck your Stripe dashboard for declined payments or error messages.
\r\nProblem: Payment Succeeds But No Order Created
\r\nThis is almost always a webhook issue:
\r\nCheck your Stripe webhook configuration. Go to Stripe Dashboard, Developers, Webhooks.
\r\nVerify the webhook URL is correct: https://yourdomain.com/shop/webhook (include the trailing slash).
\r\nEnsure the webhook is listening for payment_intent.succeeded and payment_intent.payment_failed events.
\r\nCheck that STRIPE_WEBHOOK_SECRET in your .env matches the webhook signing secret in Stripe.
\r\nVerify your webhook secret is from the same mode (test or live) as your API keys.
\r\nIn Stripe, click on the webhook and check the \"Event log\" tab to see if events were delivered successfully.
\r\nIf events show \"Failed\" with 4xx or 5xx errors, check your application logs: sudo journalctl -u ebuilder | grep webhook
\r\nTest the webhook manually by clicking \"Send test webhook\" in Stripe.
\r\nEnsure your domain's SSL certificate is valid. Stripe requires HTTPS.
\r\nMake sure your server's firewall is not blocking inbound requests from Stripe.
\r\nProblem: Orders Created But Downloads Not Available
\r\nIf orders appear in the admin but customers cannot download files:
\r\nVerify the product has files attached. Go to Admin, Shop, Products, edit the product, and check the Downloads section.
\r\nCheck that download files exist in data/media/downloads/.
\r\nVerify download limits are not set to zero for the product.
\r\nCheck the order details in Admin, Shop, Orders to ensure downloads_remaining is greater than zero.
\r\nReview application logs for permission errors when serving files: sudo journalctl -u ebuilder | grep download
\r\n\r\n
Email Issues
\r\nProblem: Emails Not Sending
\r\nIf order confirmations or password reset emails are not delivered:
\r\nCheck your email configuration in .env. Verify EMAIL_HOST, EMAIL_PORT, EMAIL_HOST_USER, and EMAIL_HOST_PASSWORD are correct.
\r\nFor Gmail, ensure you are using an App Password, not your regular Gmail password.
\r\nTest email sending manually: source venv/bin/activate then python manage.py test_email --to your@email.com
\r\nCheck for error messages in the output.
\r\nVerify EMAIL_USE_TLS is set to True for port 587 or False for port 465 (SSL).
\r\nCheck that your SMTP provider allows sending from the address specified in DEFAULT_FROM_EMAIL.
\r\nSome email providers require you to verify sender addresses before allowing outbound mail.
\r\nCheck your server's firewall allows outbound connections on port 587 or 465.
\r\nProblem: Emails Go to Spam
\r\nIf emails are being delivered but marked as spam:
\r\nConfigure SPF and DKIM records for your domain. Check your email provider's documentation for specific DNS records to add.
\r\nUse a domain-based FROM email address rather than a generic Gmail address.
\r\nAvoid spam trigger words in email subject lines and content.
\r\nConsider using a transactional email service like SendGrid, Mailgun, or Amazon SES instead of Gmail for production.
\r\nAsk customers to whitelist your email address.
\r\nProblem: Email Configuration Not Working from Admin
\r\nIf you set email settings in Admin, Shop Settings but emails still fail:
\r\nRemember that .env settings take precedence over admin settings for self-hosted installations.
\r\nTo use admin settings, temporarily comment out the EMAIL_* variables in your .env file.
\r\nRestart the service after changing .env: sudo systemctl restart ebuilder
\r\nFor production, we recommend setting email configuration in .env for consistency and easier version control.
\r\n\r\n
Permission Errors
\r\nProblem: Permission Denied on Media Files
\r\nIf you see permission errors when uploading files:
\r\nFix ownership of the data directory to the user running the service: sudo chown -R youruser:youruser /home/user/ebuilder/data
\r\nRestart the service: sudo systemctl restart ebuilder
\r\nCheck directory permissions: ls -la data/media
\r\nDirectories should be 755 and files should be 644.
\r\nProblem: Cannot Write to Database
\r\nIf you see \"unable to open database file\" or similar errors:
\r\nCheck database directory permissions: ls -la data/db
\r\nFix ownership: sudo chown -R youruser:youruser data/db
\r\nEnsure the database file itself is writable: chmod 644 data/db/db.sqlite3
\r\nVerify disk space is not full: df -h
\r\n\r\n
Performance Issues
\r\nProblem: Site Loads Slowly
\r\nIf your site is noticeably slow:
\r\nCheck server resource usage: top or htop
\r\nIf CPU is consistently high, investigate what processes are consuming resources.
\r\nIf memory usage is near 100%, consider upgrading to a server with more RAM.
\r\nReview application logs for slow database queries: sudo journalctl -u ebuilder | grep slow
\r\nEnsure collectstatic has been run to serve static files efficiently.
\r\nCheck your network latency between your location and the server.
\r\nConsider using a CDN for static assets if serving a global audience.
\r\nReview and optimize any custom code or templates you have added.
\r\nProblem: High Memory Usage
\r\nIf the application uses excessive memory:
\r\nCheck current usage: free -h
\r\nRestart the service to clear any memory leaks: sudo systemctl restart ebuilder
\r\nConsider increasing your server's RAM if you have many products or high traffic.
\r\nReview logs for errors that might indicate a memory leak.
\r\nProblem: Database Growing Large
\r\nIf your database file grows unexpectedly large:
\r\nCheck database size: ls -lh data/db/db.sqlite3
\r\nReview your data for unnecessary test orders or content that can be deleted.
\r\nVacuum the database to reclaim space: python manage.py dbshell, then run: VACUUM;
\r\nThis optimizes the database file but does not delete data.
\r\nConsider implementing regular cleanup of old orders if appropriate for your business.
\r\n\r\n
Update and Migration Issues
\r\nProblem: Errors After Update
\r\nIf you encounter errors after updating to a new version:
\r\nCheck that you ran migrations: source venv/bin/activate then python manage.py migrate
\r\nCheck that you collected static files: python manage.py collectstatic --no-input
\r\nReview the CHANGELOG file included with the update for any special instructions.
\r\nCheck application logs: sudo journalctl -u ebuilder -n 100
\r\nIf the issue is severe, restore your backup and roll back to the previous version.
\r\nReport the issue to support with full error messages and steps to reproduce.
\r\nProblem: Migration Fails
\r\nIf database migrations fail during an update:
\r\nCheck the specific error message in the output carefully.
\r\nEnsure no other processes are accessing the database. Stop the service first: sudo systemctl stop ebuilder, then run migrations directly: python manage.py migrate
\r\nIf a specific migration is failing, note the app name and migration number.
\r\nRestore from backup if the migration cannot be completed.
\r\nContact support with the full error message for assistance.
\r\n\r\n
Getting Additional Help
\r\nIf you have tried the troubleshooting steps above and still need assistance:
\r\nBefore Contacting Support:
\r\nTake note of the exact error message you are seeing.
\r\nCheck application logs: sudo journalctl -u ebuilder -n 100 > logs.txt
\r\nNote what you were doing when the problem occurred.
\r\nDocument the steps you have already tried.
\r\nPrepare any relevant screenshots.
\r\nInformation to Include:
\r\nYour eCommerce Builder version number.
\r\nYour server's operating system and version.
\r\nYour Python version: python3 --version
\r\nRelevant sections of your .env file (remove actual keys and passwords).
\r\nFull error messages and stack traces from logs.
\r\nContacting Support:
\r\nEmail: djangify@djangify.com
\r\nSubject line: \"Self-Hosted Support: Brief Description of Issue\"
\r\nInclude all information listed above.
\r\nBe as specific as possible about the problem and what you have tried.
\r\nSupport Limitations:
\r\nSupport for the self-hosted version covers bugs in the application code and assistance understanding documentation.
\r\nSupport does not include custom modifications, server setup assistance beyond the provided documentation, or troubleshooting issues caused by modifications you have made to the code.
\r\nFor custom development or hands-on server assistance, consider the managed hosting option where all infrastructure is handled for you.
\n\n