Troubleshooting

Fix common Nuxt Photo problems by starting with the visible symptom.

The album is unstyled or moves after loading

Keep the required structure CSS enabled:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@lupinum/nuxt-photo'],
  nuxtPhoto: { css: 'all' },
})

Use css: 'structure' when your own CSS supplies the visual theme. Every photo must also have accurate width and height values. These values let the browser reserve space before the image loads.

PhotoAlbum, PhotoCarousel, and a standalone Photo create the required lightbox context by default. Lower-level components such as PhotoTrigger must be inside LightboxProvider.

If lightbox was false when a ready-made component mounted, changing it to true does not create a provider. Remount the component with a new :key, or mount it only after the option is known. Lightbox capability is a setup-time option.

PhotoGroup.photos is the complete, ordered collection. Every descendant Photo or PhotoAlbum item must have an ID in that collection.

vue

<PhotoGroup :photos="[...landscapes, ...portraits]">
  <PhotoAlbum :photos="landscapes" />
  <PhotoAlbum :photos="portraits" />
</PhotoGroup>

Nuxt Photo warns when a descendant registers an ID that is missing from the group. It does not add that photo implicitly because DOM mount order is not a stable navigation order.

Photo data throws an error

Check that each item has a non-empty string id, a non-empty src, and positive finite width and height values. IDs must be unique in a collection.

Collection components can discard invalid items when losing those items is acceptable:

vue

<PhotoAlbum :photos="photos" validation="drop" @invalid-photos="reportInvalidPhotos" />

Photo remains strict and always throws for invalid data.

Nuxt Image rejects a remote URL

Add every remote image host to the Nuxt Image domains list. Use hostnames, not complete URLs:

nuxt.config.ts

export default defineNuxtConfig({
  image: {
    domains: ['images.example.com'],
  },
})

Also confirm that @nuxt/image is installed and registered when you explicitly select provider: 'nuxt-image'. The default auto mode uses the native adapter when Nuxt Image is absent.

A placeholder remains visible

This is expected after the requested image fails. The placeholder stays behind the broken request instead of leaving an empty frame. It disappears after a successful load and resets when the adapter-resolved src, srcset, or sizes changes.

Check the final image URL in the browser network panel. A successful request is required to remove the placeholder.

A custom thumbnail ignores image configuration

A raw <img> bypasses the Nuxt Photo image adapter. Render PhotoImage in the slot when the custom thumbnail should retain native, Nuxt Image, or custom adapter behavior.

A Nuxt import fails under pnpm

Nuxt applications should import public symbols from @lupinum/nuxt-photo/app. Importing @lupinum/vue-photo directly requires that package to be installed as a direct dependency.

Server and client HTML do not match

Do not create signed URLs from the current time or random state while rendering. Create them before render and place the stable result on each PhotoItem.

Also keep the photo collection, dimensions, and defaultContainerWidth deterministic between server rendering and hydration.

RTL changes do not update a carousel

Without a direction prop, PhotoCarousel reads inherited direction when it mounts. Bind the prop when the direction can change at runtime:

vue

<PhotoCarousel :photos="photos" :direction="localeDirection" />

Use either 'ltr' or 'rtl'.

The opening animation jumps

Use the default transition="auto". It fades when the thumbnail is not visible enough for a reliable opening animation. Check that thumbnail IDs and dimensions match the active photo. Programmatic opening without a visible thumbnail also uses a fade.

After a fix, test selecting a thumbnail, next and previous navigation, Escape, focus restoration, mobile width, and your application direction.