Troubleshooting

Common Errors & Fixes

502 Bad Gateway

Upstream API provider is down or returning an error.

Check provider status: curl https://api.featherless.ai/v1/models -H "Authorization: Bearer YOUR_KEY"
Check curl https://api.arliai.com/v1/models -H "Authorization: Bearer YOUR_KEY"
If both work directly, the issue is in the gateway routing — check nginx error logs
If the upstream is down, wait and retry with exponential backoff

429 Rate Limited

Too many requests. The response includes a Retry-After header.

Read the Retry-After header and wait that many seconds
For Arli AI image: max 6 parallel requests — check GET /v1/parallel-requests
Reduce request frequency or batch requests sequentially

401 Unauthorized

Missing or invalid API key.

Verify the Authorization: Bearer sk-YOUR_KEY header is present
Check your key at the provider dashboard (Featherless or Arli)
Note: api.kim8.s4s.host does not require keys (uses internal ones)

404 Not Found

Endpoint or model does not exist.

Check the endpoint URL spelling
Verify the model name via GET /v1/models
Some models may have been renamed or removed

500 Internal Server Error

Server-side error. Check logs.

Check nginx error log: tail -20 /var/log/nginx/test.error.log
Check PHP-FPM log: tail -20 /var/log/php8.3-fpm.log
Restart PHP-FPM: systemctl restart php8.3-fpm

CSS/JS Not Loading (Mixed Content)

Styles or scripts fail to load on HTTPS pages.

All resources use relative paths (/assets/css/app.css) — should auto-resolve
If using absolute URLs, ensure they use https://
Check browser console for CSP violations

How to Check Logs

Nginx Logs

tail -f /var/log/nginx/test.access.log
tail -f /var/log/nginx/test.error.log
tail -100 /var/log/nginx/test.error.log | grep "error"

PHP-FPM Logs

tail -f /var/log/php8.3-fpm.log
journalctl -u php8.3-fpm -f

System Logs

journalctl -u nginx -f
journalctl -u certbot --since "1 hour ago"

All Site Logs

ls /var/log/nginx/*.log
ls /var/log/nginx/ | grep -E "(access|error)"

How to Restart Services

nginx -t && systemctl reload nginx
systemctl restart nginx
systemctl restart php8.3-fpm
systemctl status nginx
systemctl status php8.3-fpm
systemctl status mariadb

How to Add a New Site

Create the home directory:

mkdir -p /home/newsite/{includes,assets/{css,js,icons},api,endpoints,help}

Copy shared assets:

cp /home/test/includes/security.php /home/newsite/includes/
cp /home/test/includes/functions.php /home/newsite/includes/
cp -r /home/test/assets/css /home/newsite/assets/
cp -r /home/test/assets/js /home/newsite/assets/

Create an index.php with require_once __DIR__ . '/includes/security.php';

Create the Nginx vhost:

server {
    listen 80;
    listen [::]:80;
    server_name newsite.kim8.s4s.host;
    return 301 https://newsite.kim8.s4s.host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name newsite.kim8.s4s.host;

    ssl_certificate /etc/letsencrypt/live/newsite.kim8.s4s.host/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/newsite.kim8.s4s.host/privkey.pem;

    root /home/newsite;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location ~ /\.(?!well-known) {
        deny all;
    }
}

Enable and test:

ln -s /etc/nginx/sites-available/newsite.kim8.s4s.host.conf /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Get SSL certificate:

certbot --nginx -d newsite.kim8.s4s.host

Set up DNS: Add an A record for newsite.kim8.s4s.host pointing to the server IP
Verify: curl -I https://newsite.kim8.s4s.host

How to Rotate SSL Certificates

Certificates are auto-renewed via certbot cron. To manually manage:

Check Current Certificates

certbot certificates

Force Renewal

certbot renew --force-renewal

Renew a Specific Certificate

certbot certonly --nginx -d test.kim8.s4s.host

Reload Nginx After Renewal

systemctl reload nginx

Test Auto-Renewal (Dry Run)

certbot renew --dry-run

Check Cron Job

systemctl list-timers | grep certbot
cat /etc/cron.d/certbot

FAQ

Why am I getting a blank page?

Check PHP error logs. Common causes: syntax error in PHP, missing includes, or a fatal error. Enable display_errors temporarily for debugging: ini_set('display_errors', 1);

Why are API requests slow?

Large models (70B+) take longer to generate. Use smaller models for faster responses. Check upstream provider status. Enable response streaming if supported.

How do I update the shared CSS/JS?

Edit /home/test/assets/css/app.css and /home/test/assets/js/app.js. Other sites symlink or copy these files. Use versioned filenames for cache busting: app.v2.css.

Can I use the API without authentication?

Yes, via the API gateway at api.kim8.s4s.host which uses internal keys. Direct provider calls require your own API key.

How do I switch from PHP 8.3 to a different version?

apt install php8.x-fpm php8.x-mysql
# Update nginx socket path: unix:/run/php/php8.x-fpm.sock
systemctl disable php8.3-fpm
systemctl enable php8.x-fpm
systemctl restart php8.x-fpm
nginx -t && systemctl reload nginx

How do I back up a site?

tar czf /backup/test-$(date +%Y%m%d).tar.gz -C /home test/
tar czf /backup/vision-$(date +%Y%m%d).tar.gz -C /home vision/

What if DNS isn't resolving?

Check the wildcard DNS record for *.kim8.s4s.host. Verify with dig newsite.kim8.s4s.host or nslookup newsite.kim8.s4s.host.