Skip to content

Troubleshooting & FAQ

Panel Won't Start

Check the service status:

systemctl status starkone
journalctl -u starkone -n 50

Common causes:

  • Port 2087 already in use: lsof -i :2087
  • Database locked: another process has the SQLite file open
  • Missing /etc/starkone/starkone.env

Can't Log In

Reset admin password via CLI:

starkone-cli reset_password admin new_password

Check if the panel service is running:

curl -sk https://localhost:2087/health

2FA locked out: Disable 2FA via the database:

sqlite3 /etc/starkone/starkone.db \
  "UPDATE users SET totp_secret = '' WHERE username = 'admin';"

Website Not Loading

  1. Check if nginx/apache is running: systemctl status nginx
  2. Check vhost config: nginx -t
  3. Check PHP-FPM: systemctl status php8.2-fpm
  4. Check website permissions: starkone-cli fix_permissions <username>

SSL Certificate Issues

Let's Encrypt rate limit hit: Wait 24 hours or use the --staging flag for testing.

Certificate not renewing: Check that port 80 is open and not blocked by CSF.

# Manual renewal
starkone-cli issue_letsencrypt example.com

MySQL Won't Connect

# Check service
systemctl status mysql

# Check panel connectivity
mysql --defaults-file=/etc/starkone/.mysql.conf -e "SELECT 1;"

File Manager: Permission Denied

starkone-cli fix_permissions <username>

API Returns 401

  • Token expired - log in again to get a fresh token
  • JWT_SECRET changed in starkone.env - all sessions are invalidated

API Returns 403: Plugin Not Enabled

Enable the plugin via Settings → Plugins or:

curl -X POST https://<server>:2087/api/plugins/<id>/enable \
  -H "Authorization: Bearer <token>"

API Returns 403: License Required

The license key is missing or invalid. Navigate to the panel root (port 2087) to enter or reactivate the license.

High Memory Usage

Check which processes are consuming memory:

GET /api/system/processes

Or via the panel System → Processes section.

Consider: - Reducing MySQL innodb_buffer_pool_size - Limiting PHP-FPM pool sizes per website - Enabling Varnish to reduce PHP spawning

Panel Update Failed

# Manual update
systemctl stop starkone
curl -fsSL https://dl.starkone.io/install.sh | bash

Nginx Config Broken After Switch

# Rewrite all vhosts
POST /api/system/rewrite-all

# Or via CLI
starkone-cli rewrite_all

Database Migration Error

Check the migration log:

journalctl -u starkone | grep migration

Apply a specific migration manually:

sqlite3 /etc/starkone/starkone.db < \
  /usr/share/starkone/migrations/NNN_name.up.sql

Getting Help