Error "Ref not found. Ensure you have the correct ref and try again." only at ISR Functions


I use vercel to deploy my next+prismic project and i'm having the "Ref not found. Ensure you have the correct ref and try again." error only on pages that use the ISR Functions and when i'm visiting the ISR pages i get the " Application error: a server-side exception has occurred (see the server logs for more information)." message. Pages that use generateStaticParams have no issue and the builds always complete succesful.

If i revoke the access token and add a new one and redeploy the same deployment that failed, it will work perfectly, but then if i commit again the new deployment will have the above error again.

I have tried to change my prismic api to public and to add the VERCEL_FORCE_NO_BUILD_CACHE variable but nothing changed, also locally everything works correctly.

Have anyone faced the same issue?

Here is the entire error i get in vercel:

q [Error]: Ref not found. Ensure you have the correct ref and try again. Master ref is: xxx
    at z.fetch (/var/task/.next/server/chunks/757.js:1:11855)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async z.getFirst (/var/task/.next/server/chunks/757.js:1:5114)
    at async z.getSingle (/var/task/.next/server/chunks/757.js:1:6099)
    at async h (/var/task/.next/server/app/xxx/page.js:1:16325) {
  url: 'https://xxx',
  response: {
    type: 'api_notfound_error',
    message: 'Ref not found. Ensure you have the correct ref and try again. Master ref is: xxx'

Thank you in advance

Hi @john-mantas. I wasn't sure about this so I asked some of my colleagues about it. Here's the response I received:

It sounds like they are using the App Router since they refer to generateStaticParams. The App Router no longer has a concept of "incremental static regeneration," and instead has on-demand revalidation. Let's ask to confirm that they are using on-demand revalidation.

They likely do not have caching set up correctly. "Ref not found" typically happens when a cached /api/v2 request returns an expired ref. The fact that everything works locally, where they may have caching disabled, points to a caching misconfiguration.

Their @prismicio/client createClient() calls should contain this recommended fetchOptions:

const client = prismic.createClient(repositoryName, {
    process.env.NODE_ENV === "production"
      ? { next: { tags: ["prismic"] }, cache: "force-cache" }
      : { next: { revalidate: 5 } },

Source: nextjs-starter-prismic-minimal/src/prismicio.js at cfd926cb45cb459baa1660963fdf4770fe5ecde5 · prismicio-community/nextjs-starter-prismic-minimal · GitHub

In the on-demand revalidation route handler (e.g. /api/revalidate), revalidateTag("prismic") should be called to revalidate all Prismic network requests. See: nextjs-starter-prismic-minimal/src/app/api/revalidate/route.js at cfd926cb45cb459baa1660963fdf4770fe5ecde5 · prismicio-community/nextjs-starter-prismic-minimal · GitHub

The revalidation endpoint should be called when Prismic documents are published or unpublished.

I hope this helps.

Hi @Levi. I do use the App Router and by "ISR Functions" (this is how it was called in the vercel dashboard) i mean routes that do not export a generateStaticParams function.

My createClient() contains the same fetchOptions as the minimal starter repo and also my /api/revalidate is the same.

Does the revalidation endpoint should be called with a webhook anytime a document is published/unpublished or should it be called somehow before the route gets generated?

I haven't set up any webhooks in prismic yet and for now i'm just rebuilding the project only with my git commits.

Also, does the master ref change when a document is published or unpublished?

PS. I'm adding some screenshots from the dashboard to better understand which pages i'm talking about, which btw today has been changed and the "ISR Functions" includes only the statically generated routes instead of the on-demand that it was when i opened this topic. The problem occurs at the "/photos" routes.

and this is the error, which is also different today, it used to log 3-4 errors instead of just one

You need to set up a Prismic webhook to invalidate your Prismic network requests. Doing so prompts Next.js to fetch fresh data on the next request.
This blog post describes how to set up the webhook:

The master ref does change every time a document in published or unpublished.

@Levi Thank you for the informations, i hadn't read the guide you posted.

It just works now, i don't know if either vercel or prismic changed something, but it just started working without me changing anything and it seems that still works after multiple commits and deploys i have done the last 2 days.

I'm keeping an eye on it and i will use the revalidation webhook if this error comes up again.

1 Like