Solución de problemas y preguntas frecuentes

Si encuentras algún problema al usar PhanTerm, consulta la siguiente guía de solución de problemas para dudas frecuentes.

1. Problemas de renderizado del terminal o superposición de texto

Síntoma: Después de ingresar al terminal, algunas aplicaciones de línea de comandos complejas (como aquellas con comandos largos que se ajustan automáticamente, registros Git de varios colores) muestran texto desalineado, imágenes residuales de texto o posiciones incorrectas del cursor.

Solución: Esto a menudo se debe a que las dimensiones de ancho y alto del terminal detectadas por el sistema operativo no están sincronizadas. Intenta arrastrar manualmente para ajustar el tamaño de la ventana. Después de que la capa de escucha de PhanTerm reciba el evento de cambio de tamaño (Resize), forzará el envío de un reinicio de dimensión correcto al PTY remoto, lo que resolverá más del 90% de los problemas de visualización en pantalla.

2. No se puede conectar al servidor (Connection Timed Out)

Síntoma: Se muestra continuamente la animación de carga con Connecting... y luego se emite un aviso de tiempo de espera agotado (timeout) o red inalcanzable.

Solución:

1. Primero verifica que la IP y el puerto (especialmente puertos personalizados distintos al 22) que ingresaste sean correctos.
2. Confirma que el firewall de la máquina remota o el grupo de seguridad de tu proveedor en la nube ha permitido el acceso a tu IP pública local.
3. Si el servidor de destino está en un entorno de red interna, es posible que necesites configurar un jump host (ProxyJump) en la configuración de conexión para lograr acceso mediante túnel.

3. Autenticación de clave SSH rechazada (Permission Denied)

Síntoma: La autenticación por clave ya está configurada, pero aún solicita una contraseña o la conexión falla.

Solución:

1. Comprobar la ruta: Revisa que la ruta IdentityFile que proporcionaste exista y sea válida.
2. Comprobación de formato: Asegúrate de haber proporcionado un archivo de clave privada (como id_rsa o id_ed25519) y no un archivo de clave pública con la extensión .pub.
3. Agent del sistema: Si elegiste utilizar ssh-agent o Pageant del sistema para gestionar la identidad, asegúrate de que estos servicios en segundo plano estén en ejecución y de que tu clave se haya cargado correctamente en el sistema mediante el comando ssh-add.

4. Advertencia de pantalla roja por incompatibilidad de huella de clave del host

Síntoma: Al conectar aparece un cuadro de alerta rojo llamativo que indica que la firma de la clave del host es incorrecta.

Solución: ¡No la omitas a la ligera! Primero comunícate con el administrador de tu servidor. Solo debes considerar que esto es normal bajo estas dos circunstancias:

1. El sistema operativo del servidor acaba de ser reinstalado.
2. El administrador te informó que recientemente han rotado los certificados de seguridad SSH.

Si confirmas que es seguro, puedes ingresar a tu directorio de configuración local (consulta la Referencia de configuración), abrir known_hosts.yaml, eliminar manualmente la fila del registro en conflicto correspondiente e intentarlo de nuevo.