Troubleshooting

Most problems come down to a handful of causes: PHP version, file permissions, database credentials, web-server rewriting or a missing worker. This page lists the symptoms operators hit most and how to fix each one. When in doubt, your PHP error log is the fastest way to the truth.

Installation problems

"Your PHP version is not supported"

TubePress requires PHP 8.2 or newer, enforced by a parse-safe version guard that runs before anything else. Switch the PHP version in your hosting panel (or point the vhost at a newer PHP-FPM socket) and reload. See Requirements.

"Could not connect to the database"

During the installer's database step, double-check the host (often localhost or 127.0.0.1), database name, user and password, and that the user has privileges on that database. The database must already exist — the installer creates tables, not the schema itself.

The installer can't write configuration / a "not writable" error

The web server needs write access to config/ and storage/ during setup. Make those directories writable by the PHP user, then retry. See the permissions guidance in Installation.

I finished installing but /install still loads

Installation writes config/installed.php. If it is missing the app thinks it is uninstalled; if setup completed, that file should exist and the installer locks itself. Re-check that config/ was writable.

The site loads but pages 404

If the home page works but every other URL returns 404, URL rewriting is not reaching the front controller.

• Apache — confirm mod_rewrite is enabled and AllowOverride All is set so the bundled .htaccess is honoured.
• Nginx — your location / must fall through to the front controller, e.g. try_files $uri $uri/ /index.php?$query_string;. See Architecture for the web-server notes.

Login & admin access

I can't find the admin login

If you set a custom admin URL for security, the panel no longer lives at /admin — it answers only at your secret path. Recover it from the settings table if you have database access. See Security.

Two-factor is locking me out

If you lose your authenticator, disable the user's TOTP in the database (the relevant column on the users table) to regain access, then re-enrol. Details in Security.

Uploads & media

Large uploads fail or time out

Raise the PHP limits upload_max_filesize and post_max_size, and on Nginx increase client_max_body_size. The demo allows multi-gigabyte uploads via a high client_max_body_size; mirror that on your server for big files.

A video won't play

Newly uploaded videos may still be processing until transcoding finishes. Confirm the format is web-deliverable, that the rendition files exist in storage, and that your server sends the correct MIME type for .mp4/.webm. See Player.

Thumbnails or previews are missing

Thumbnail and preview generation needs the GD or Imagick extension (and FFmpeg for video-derived frames). Verify they are installed and that uploads/ is writable.

Transcoding is stuck

If jobs sit in the queue and never complete:

• Confirm FFmpeg is installed wherever transcoding runs (local server or a remote worker).
• If you use remote transcode servers, check the worker is running and its API key matches the one configured in the admin.
• Make sure the scheduler is ticking (see below) — job dispatch and retry run on the pseudo-cron.

Scheduled work isn't running

The pseudo-cron only fires on page renders. On a quiet site the heartbeat keeps it alive — make sure heartbeat_enabled is 1. If you disabled it, either re-enable it or add a system cron entry that hits your site periodically.

Email isn't sending

Configure SMTP under Email & notifications and use the built-in Send test email button to confirm. If tests fail, verify the SMTP host/port/credentials and that your host allows outbound mail; for deliverability, set up SPF/DKIM on your domain.

Performance

For a snappy site at scale: enable OPcache, give PHP enough memory, keep MySQL on the same network as PHP, and leave the CTR recalculation and other scheduled tasks running. TubePress ships with the indexes and chunked jobs needed for large libraries — see Maintenance.

Updates fail

If an update will not apply, confirm the core files are writable by the PHP user and that you are on PHP 8.2+. Always back up before updating so you can roll back. See Updating.

Still stuck?

Gather the exact error message and the relevant log lines, then open a ticket from your dashboard or the in-admin support widget. The more context you include — PHP version, web server, and what you were doing — the faster it is resolved. See Announcements & support.