Fix image upload problems

Start with one small PNG. Open your browser’s Network panel, insert the image, and follow the request from upload to the saved document. Do this in a test document, not a customer’s draft.

First setup: choose where images live

The editor inserts content; your application stores uploaded files. Choose a persistent folder or object store, configure an upload endpoint, and return a browser-accessible image URL. A server disk path is not an image URL.

1. Start with the runnable demo for your server language.
2. Use the upload URL or custom handler documented for your installed version. Do not register competing handlers.
3. Follow file storage setup to disable Base64 embedding when your application requires uploaded images.
4. Insert, paste and drop an image separately. Save, reload, and open the saved image URL in the context where readers will view the document.

Find your symptom

No upload request appears

Check the console for initialization errors and confirm the handler script loaded before the editor used it. If the HTML contains a data:image/ source, the picture was embedded rather than uploaded. Check the actual editor configuration, not just the file you intended to deploy.

401 or 403: the request is rejected

Inspect authentication, CSRF validation and folder authorization. A login page returned with status 200 is also a failed upload. For cross-origin uploads, check cookie and CORS configuration on both origins. Keep access checks enabled; use your application’s authenticated upload flow.

413: the file is too large

Check the reverse proxy, web server, framework multipart limit and application limit. The smallest limit wins. Test just below and above your intended limit. Browser-side resizing can reduce photographs, but server limits must still protect the endpoint.

200 response, but no image

Inspect the response body and content type. It must follow a supported response format, not a success message, HTML error page or filesystem path. For a custom handler, call its completion callback once with the saved URL or an error.

Upload succeeds, then the image URL returns 404

Open the returned URL directly. Check the public URL prefix, virtual directory, case-sensitive filename, static-file serving and persistent storage. A relative URL may resolve under a different path on the published page. Test the URL from both the editor page and the reader page.

Images disappear after a restart or deployment

Check whether uploads were written to a temporary or replaced application directory. Use persistent storage and include it in your backup policy. A deployment should not replace user uploads with files from a demo package.

Check the saved document, not just the preview

A preview can appear before the upload finishes. Read the submitted HTML, the stored value, and the HTML returned after reload. Confirm the image points to its final URL. An unresolved blob: URL belongs to a browser session; it is not durable storage.

If images work in the editor but disappear after saving, check the timing of submission, server validation and your HTML sanitizer’s image policy. Do not disable sanitization to make an image appear. See saving rich text with images.

Production checks

• Validate file type, decoded dimensions and size on the server.
• Generate storage names; do not trust uploaded paths or filenames.
• Apply per-user or per-tenant permissions to uploads and gallery access.
• Keep private images behind authorized delivery; a public URL is public even when the editor page requires login.
• Test rejection, cancellation and a slow connection as well as success.

What to send support

Include your editor version, framework, a minimal configuration, the failing action, HTTP status and a redacted response. State whether the problem happens before upload, after insertion, or after save and reload. Remove cookies, tokens, private image URLs and customer content before sharing logs.

Server examples: ASP.NET Core, Web Forms and MVC, PHP. Try the drag-and-drop image demo.