Solucionar problemas de carga de imágenes

Empieza con un PNG pequeño. Abre el panel Network del navegador, inserta la imagen y sigue la solicitud desde la carga hasta el documento guardado. Hazlo en un documento de prueba, no en el borrador de un cliente.

Configuración inicial: elige dónde se guardan las imágenes

El editor inserta contenido; tu aplicación guarda los archivos subidos. Elige una carpeta persistente o un almacén de objetos, configura un endpoint de carga y devuelve una URL de imagen accesible desde el navegador. Una ruta de disco del servidor no es una URL de imagen.

Empieza con la demo ejecutable para el lenguaje de tu servidor.
Usa la URL de carga o el controlador personalizado documentados para tu versión instalada. No registres controladores que compitan entre sí.
Sigue la configuración del almacenamiento en archivos para desactivar la incrustación en Base64 cuando tu aplicación exija imágenes subidas.
Inserta, pega y suelta una imagen por separado. Guarda, recarga y abre la URL de la imagen guardada en el contexto en el que los lectores verán el documento.

Encuentra tu síntoma

No aparece ninguna solicitud de carga

Busca errores de inicialización en la consola y confirma que el script del controlador se cargó antes de que el editor lo usara. Si el HTML contiene un origen data:image/, la imagen se incrustó en lugar de subirse. Comprueba la configuración real del editor, no solo el archivo que pretendías desplegar.

401 o 403: la solicitud se rechaza

Revisa la autenticación, la validación CSRF y la autorización de carpetas. Una página de inicio de sesión devuelta con estado 200 también es una carga fallida. Para cargas entre orígenes, comprueba la configuración de cookies y de CORS en ambos orígenes. Mantén activadas las comprobaciones de acceso; usa el flujo de carga autenticado de tu aplicación.

413: el archivo es demasiado grande

Comprueba el proxy inverso, el servidor web, el límite multipart del framework y el límite de la aplicación. Gana el límite más pequeño. Prueba justo por debajo y por encima del límite que pretendes. Redimensionar en el navegador puede reducir las fotografías, pero los límites del servidor tienen que seguir protegiendo el endpoint.

Respuesta 200, pero sin imagen

Revisa el cuerpo y el tipo de contenido de la respuesta. Debe seguir un formato de respuesta admitido, no ser un mensaje de éxito, una página HTML de error ni una ruta del sistema de archivos. Con un controlador personalizado, llama a su callback de finalización una sola vez con la URL guardada o con un error.

La carga funciona, pero luego la URL de la imagen devuelve 404

Abre directamente la URL devuelta. Comprueba el prefijo de la URL pública, el directorio virtual, el nombre de archivo que distingue mayúsculas y minúsculas, el servicio de archivos estáticos y el almacenamiento persistente. Una URL relativa puede resolverse bajo otra ruta en la página publicada. Prueba la URL tanto desde la página del editor como desde la página del lector.

Las imágenes desaparecen después de un reinicio o un despliegue

Comprueba si las cargas se escribieron en un directorio temporal o en un directorio de la aplicación que se reemplaza. Usa almacenamiento persistente e inclúyelo en tu política de copias de seguridad. Un despliegue no debe sustituir las cargas de los usuarios por archivos de un paquete de demostración.

Comprueba el documento guardado, no solo la vista previa

Una vista previa puede aparecer antes de que termine la carga. Lee el HTML enviado, el valor guardado y el HTML devuelto después de recargar. Confirma que la imagen apunta a su URL definitiva. Una URL blob: sin resolver pertenece a una sesión del navegador; no es almacenamiento duradero.

Si las imágenes funcionan en el editor pero desaparecen al guardar, revisa el momento del envío, la validación del servidor y la política de imágenes de tu saneador de HTML. No desactives el saneamiento para que aparezca una imagen. Consulta guardar texto enriquecido con imágenes.

Comprobaciones para producción

Valida en el servidor el tipo de archivo, las dimensiones decodificadas y el tamaño.
Genera los nombres de almacenamiento; no confíes en las rutas ni en los nombres de archivo subidos.
Aplica permisos por usuario o por inquilino a las cargas y al acceso a la galería.
Mantén las imágenes privadas detrás de una entrega autorizada; una URL pública es pública aunque la página del editor exija iniciar sesión.
Prueba el rechazo, la cancelación y una conexión lenta, además del caso de éxito.

Qué enviar a soporte

Incluye la versión del editor, el framework, una configuración mínima, la acción que falla, el estado HTTP y una respuesta con los datos sensibles ocultos. Indica si el problema ocurre antes de la carga, después de la inserción o después de guardar y recargar. Quita las cookies, los tokens, las URL de imágenes privadas y el contenido de clientes antes de compartir los logs.

Ejemplos de servidor: ASP.NET Core, Web Forms y MVC, PHP. Prueba la demo de arrastrar y soltar imágenes.