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

Hi,

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

1 Like

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, {
  routes,
  fetchOptions:
    process.env.NODE_ENV === "production"
      ? { next: { tags: ["prismic"] }, cache: "force-cache" }
      : { next: { revalidate: 5 } },
  ...config,
});

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:
https://prismic.io/blog/how-to-use-prismic-with-nextjs-app-router#set-up-ondemand-revalidation

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

1 Like

@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

Hello,

I am facing the same issue with Next.js 14.1.0, with my createClient configured as:

export const createClient = (config: prismicNext.CreateClientConfig = {}) => {
  const client = prismic.createClient(repositoryName, {
    routes,
    fetchOptions:
      process.env.NODE_ENV === 'production'
        ? { next: { tags: ['prismic'] }, cache: 'force-cache' }
        : { next: { revalidate: 5 } },
    ...config
  })

  prismicNext.enableAutoPreviews({
    client,
    previewData: config.previewData,
    req: config.req
  })

  return client
}

error:
response: {
type: 'api_notfound_error',
message: 'Ref not found. Ensure you have the correct ref and try again. Master ref is

When I get the errors you are mentioning, I find that clearing my .next folder does the trick. I run
rm -rfv ./.next and then when I run bun dev or bun run build, all is good (sub npm/yarn/etc for bun)

2 Likes

Right on! Doing so did work. Thank you @nf_mastroianni :raised_hands:

2 Likes

I am having the same error while trying to implement pagination to my site
I am reading search params from the url




For this specific page I have decided to opt out of slice zone and just using my own html for it. Everything works fine in development but works in production

I have you gone into Vercel and purged the cache there? My :moneybag: (moneybag emoji) is on that to fix the discrepancy between dev and prod results.

1 Like

Redeploying the site purges the cahce and I did that but the error still persists

Hey
There was a bug in my code and I have fixed the issue
Thanks everyone

1 Like

Hi I am facing this issue too. We can just temporarily change the default prismic caching from 'force-cache' into 'no-store'. After the cache cleared we can change it back to 'force-cache'.
const client = prismic.createClient(repositoryName, { routes, fetchOptions: process.env.NODE_ENV === 'production' ? { next: { tags: ['prismic'] }, cache: 'no-store' } : { next: { revalidate: 5 } }, ...config, });