Resolución de problemas

La mayoría de los problemas se reducen a unas pocas causas: versión de PHP, permisos de archivos, credenciales de base de datos, reescritura del servidor web o un trabajador faltante. Esta página enumera los síntomas más frecuentes que encuentran los operadores y cómo resolverlos. En caso de duda, el registro de errores de PHP es el camino más rápido hacia la solución.

Problemas de instalación

"Su versión de PHP no está soportada"

TubePress requiere PHP 8.2 o superior, impuesto por un guard de versión seguro que se ejecuta antes que nada. Cambie la versión de PHP en su panel de hosting (o apunte el vhost a un socket PHP-FPM más nuevo) y recargue. Consulte Requisitos.

"No se pudo conectar a la base de datos"

Durante el paso de base de datos del instalador, verifique el host (generalmente localhost o 127.0.0.1), el nombre de la base de datos, el usuario y la contraseña, y que el usuario tenga privilegios sobre esa base de datos. La base de datos debe existir de antemano — el instalador crea las tablas, no el esquema en sí.

El instalador no puede escribir la configuración / error "not writable"

El servidor web necesita acceso de escritura a config/ y storage/ durante la configuración. Haga que esos directorios sean escribibles por el usuario de PHP y vuelva a intentarlo. Consulte la guía de permisos en Instalación.

Terminé de instalar pero /install sigue cargando

La instalación escribe config/installed.php. Si falta, la aplicación cree que no está instalada; si la configuración se completó, ese archivo debería existir y el instalador se bloquea solo. Verifique nuevamente que config/ era escribible.

El sitio carga pero las páginas dan 404

Si la página de inicio funciona pero cualquier otra URL devuelve 404, la reescritura de URL no está llegando al controlador frontal.

• Apache — confirme que mod_rewrite está habilitado y que AllowOverride All está configurado para que el .htaccess incluido sea respetado.
• Nginx — su location / debe redirigir al controlador frontal, p. ej. try_files $uri $uri/ /index.php?$query_string;. Consulte Arquitectura para las notas sobre el servidor web.

Inicio de sesión y acceso de administrador

No puedo encontrar el inicio de sesión de administrador

Si configuró una URL de administrador personalizada por seguridad, el panel ya no se encuentra en /admin — solo responde en su ruta secreta. Recupérela desde la tabla settings si tiene acceso a la base de datos. Consulte Seguridad.

La autenticación de dos factores me está bloqueando

Si pierde su autenticador, deshabilite el TOTP del usuario en la base de datos (la columna relevante en la tabla users) para recuperar el acceso, luego vuelva a inscribirse. Detalles en Seguridad.

Cargas y medios

Las cargas grandes fallan o superan el tiempo de espera

Aumente los límites de PHP upload_max_filesize y post_max_size, y en Nginx incremente client_max_body_size. La demo permite cargas de varios gigabytes con un client_max_body_size alto; replique eso en su servidor para archivos grandes.

Un video no se reproduce

Los videos recién cargados pueden seguir en estado procesando hasta que termine la transcodificación. Confirme que el formato es compatible con la web, que los archivos de representación existen en el almacenamiento y que su servidor envía el tipo MIME correcto para .mp4/.webm. Consulte Reproductor.

Las miniaturas o vistas previas faltan

La generación de miniaturas y vistas previas necesita la extensión GD o Imagick (y FFmpeg para fotogramas derivados de video). Verifique que estén instaladas y que uploads/ sea escribible.

La transcodificación está atascada

Si las tareas permanecen en la cola y nunca se completan:

• Confirme que FFmpeg está instalado donde se ejecuta la transcodificación (servidor local o un trabajador remoto).
• Si usa servidores de transcodificación remotos, verifique que el trabajador esté en ejecución y que su clave API coincida con la configurada en el administrador.
• Asegúrese de que el planificador esté funcionando (ver más abajo) — el despacho de tareas y los reintentos se ejecutan en el pseudo-cron.

El trabajo programado no se ejecuta

El pseudo-cron solo se activa en las renderizaciones de páginas. En un sitio con poco tráfico, el heartbeat lo mantiene activo — asegúrese de que heartbeat_enabled sea 1. Si lo deshabilitó, vuelva a habilitarlo o agregue una entrada de cron del sistema que acceda a su sitio periódicamente.

El correo electrónico no se envía

Configure SMTP en Correo electrónico y notificaciones y use el botón integrado Enviar correo de prueba para confirmar. Si las pruebas fallan, verifique el host/puerto/credenciales SMTP y que su hosting permita correo saliente; para la entregabilidad, configure SPF/DKIM en su dominio.

Rendimiento

Para un sitio ágil a escala: habilite OPcache, otorgue suficiente memoria a PHP, mantenga MySQL en la misma red que PHP y deje en ejecución el recálculo de CTR y otras tareas programadas. TubePress incluye los índices y las tareas fragmentadas necesarias para bibliotecas grandes — consulte Mantenimiento.

Las actualizaciones fallan

Si una actualización no se aplica, confirme que los archivos principales son escribibles por el usuario de PHP y que está en PHP 8.2+. Siempre haga una copia de seguridad antes de actualizar para poder revertir los cambios. Consulte Actualización.

¿Sigue atascado?

Recopile el mensaje de error exacto y las líneas de registro relevantes, luego abra un ticket desde su panel o el widget de soporte del administrador. Cuanto más contexto incluya — versión de PHP, servidor web y lo que estaba haciendo — más rápido se resolverá. Consulte Anuncios y soporte.