Docly Developers
Knowledge base Pitfall By design

Images that should be scaled cannot live under the # folder

In shortDocly scales and caches images on serving, but only for files it serves. Every request for a path under # answers 404 — scaled image URLs included — so an image stored under #/Data can never be linked with linkImage. Store images that should be scaled at a served path, and protect them with the publication's sign-in and shares, plus the site router if you need app-level rules. Do not build your own variant pipeline with scaleImage.
Applies to ImagesSecurityPublishingAPI
  1. 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 with docly.downloadBytes.

    Then lists and product cards need thumbnails. linkImage gives 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.scaleImage at 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.

  2. 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 by linkImage, 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 #/Data has 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.

  3. 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 call linkImage can 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 scaleImage into extra documents just because linkImage answered 404. A 404 on a scaled URL means the path is wrong or private, not that scaling is unavailable. scaleImage is 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.

Last reviewed 15 Nov 2026