Appearance
When Mirador will not display your object, the cause is almost always one of four things: a CORS failure on the cross-origin fetch, an invalid or unreachable manifest, a missing or broken ImageService, or mixed HTTP/HTTPS content. Work them in that order. This guide gives the symptom, the diagnosis and the fix that holds, for Mirador 3, the current React-based viewer.
Why is my Mirador window blank?
A blank window with no on-screen error is the signature of a CORS problem. The browser silently refuses to read JSON fetched from another origin unless the server sends the right header. Open DevTools, go to the Network tab, reload, and look for the manifest or info.json request showing as blocked. Confirm with:
bash
curl -I -H "Origin: https://viewer.example.org" \
https://images.example.org/iiif/3/leaf-12r/info.jsonIf the response lacks Access-Control-Allow-Origin, the image server is the culprit, not Mirador. Fix it at the server or proxy:
nginx
add_header Access-Control-Allow-Origin "*" always;How do I set up Mirador 3 correctly?
Mirador 3 installs via npm and mounts into a DOM element with a config object:
javascript
import Mirador from 'mirador';
Mirador.viewer({
id: 'mirador', // must match an existing <div id="mirador">
windows: [
{ loadedManifest: 'https://example.org/iiif/ms-12/manifest.json' }
]
});The two mistakes here are a id that does not match a real element (nothing renders) and a relative manifest URL (it must be absolute and HTTPS).
Why does the manifest fail to load?
If Mirador reports a failed manifest, prove the manifest is the problem before touching the viewer config. Fetch and inspect it:
bash
curl -s https://example.org/iiif/ms-12/manifest.json | jq '.["@context"], .type, (.items | length)'You want a valid v3 @context, type: "Manifest", and a non-zero canvas count. Then run it through the official Presentation API validator. A manifest that fails validation hard will be rejected silently by the loader.
Why are images blurry or refusing to zoom?
Deep zoom in Mirador depends on the canvas image body declaring a working service. If that service is missing or its id does not resolve to a valid info.json, Mirador shows the flat fallback image and zoom does nothing useful. Check the chain:
bash
# The service id from the manifest must itself return valid metadata
curl -s https://images.example.org/iiif/3/ms-12-f1r/info.json | jq '.tiles'No tiles array means the server is not advertising tiling, so the viewer cannot request zoom levels.
Common errors and their fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Blank window, console CORS error | Missing CORS header on image server | Add Access-Control-Allow-Origin at origin or proxy |
| "Manifest failed to load" | Wrong URL or invalid JSON | curl the URL; validate the manifest |
| Mixed content blocked | Manifest on HTTPS pointing to HTTP images | Serve all resources over HTTPS |
| Flat image, no zoom | Missing or broken ImageService | Ensure service id resolves to valid info.json |
| Nothing renders at all | Config id does not match a DOM element | Make the div id and config id identical |
How can I test quickly without a build?
For a smoke test, load a pre-bundled UMD build from a CDN and instantiate it inline in a plain HTML file. This rules out your build toolchain as the problem: if the CDN version shows your manifest, the issue is your bundler config; if it also fails, the issue is the manifest or CORS. Either way you have narrowed it in two minutes.
Key Takeaways
- A blank Mirador window is almost always a CORS failure, not a viewer bug.
- Use Mirador 3 (React); Mirador 2 jQuery is legacy.
- Prove the manifest is valid with curl plus the official validator before editing config.
- No zoom usually means the canvas image lacks a working ImageService.
- Serve manifest and images over HTTPS to avoid mixed-content blocks.
- A CDN UMD build is the fastest way to isolate whether the fault is yours or the data's.
Frequently Asked Questions
Why is my Mirador window blank with no error on screen?
Almost always CORS. The browser blocked the cross-origin fetch of info.json or the manifest. Open the console and network tab; a blocked request with no Access-Control-Allow-Origin header confirms it.
Which Mirador version am I setting up?
Mirador 3 is the current line, a React/Redux rewrite installed via npm and configured with a JavaScript object. Mirador 2 is legacy jQuery and should not be used for new projects.
Why does Mirador say the manifest failed to load?
Either the manifest URL is wrong or returns non-JSON, or it fails validation badly enough that the loader rejects it. Fetch the URL directly with curl and validate it before blaming the viewer.
How do I add a manifest to a Mirador 3 instance?
Pass it in the config windows array with a loadedManifest property, or add it at runtime via the catalog. The manifest must be an absolute, CORS-enabled HTTPS URL.
Why are images low resolution or not zooming?
The image body in the manifest probably lacks a working ImageService, so Mirador falls back to the static image instead of requesting tiles. Confirm the service id resolves to a valid info.json.
Can I run Mirador without a build step?
Yes, you can load a pre-bundled UMD build from a CDN and instantiate it with a small inline config, which is ideal for quick testing before committing to an npm build.