Images that should be scaled cannot live under the # folder
-
What you'll see
An application keeps uploaded images under
#— for example#/Data/files/<id>with the bytes as an embedded file — because private data belongs under #. The images are served through an API script that checks who is asking and returns the original withdocly.downloadBytes.Then lists and product cards need thumbnails.
linkImagegives a URL that answers 404, so the developer (or an AI agent) concludes that Docly's scaling cannot be used here and builds a parallel pipeline:docly.scaleImageat upload or import time, extra documents for each size, an extra query parameter on the API script. It works, costs storage and import time, fails on images the scaler cannot read, and duplicates what the platform already does. -
What's actually happening
Two documented rules meet here:
- Docly scales and converts images on serving. The URL is
<file path>/<embeddedId>/<W>x<H>x<M>/<name>.<format>, built bylinkImage, and the result is cached per size. See Scale and convert images in Docly. - A request for any path under
#answers 404, except#/Root/,#/Folder/and scripts in#/API/. A scaled-image URL is a request like any other, so an image under#/Datahas no scaled URL at all. See Sign-in and access.
The reason for putting the images under
#was access control, but a served path is not the same as a public path. On a publication with Require login, every request — pages, uploaded files and scaled images — needs a Docly session and Visit access through a share to the folder that is opened. A user who only has a share on one site cannot open files on another site. The site router runs after that check for every request, scaled images included, and can narrow access further with the application's own rules (a user list, a suspended subscription), but never widen it. - Docly scales and converts images on serving. The URL is
-
What to do
Do — images at a served path, scaled by Docly:
- Store images that should be shown in several sizes at a path the site serves — a folder in the site, or
#/Root/— not under#/Data. - Link them with
docly.linkImage(fileObject, fileObject.File, w, h, 0, name + '.webp')and register the sizes in#/images.json(Restrict and register image sizes). Client-side code that cannot calllinkImagecan build the same URL from the file's path and embeddedId. - Protect them with the publication's sign-in and shares. If the application has rules beyond shares, put them in the site router — one check in front of every file — instead of in an API script that streams the bytes.
Don't pre-scale with
scaleImageinto extra documents just becauselinkImageanswered 404. A 404 on a scaled URL means the path is wrong or private, not that scaling is unavailable.scaleImageis for one-off derivatives that need their own quality or that are written somewhere else — not a replacement for the image cache.Keep under # only files that must never be reachable by a URL, and accept that they are then served whole by your own API script.
- Store images that should be shown in several sizes at a path the site serves — a folder in the site, or
Last reviewed 15 Nov 2026