Custom Types API: newly created types not recognized by CDN Route Resolver until manual UI action

Developing with Prismic
1

Description:

When creating a new custom type via the Custom Types API and then immediately querying documents, the Route Resolver throws an "Unknown type" error for the
newly created type.

Steps to reproduce:

  1. Create a new custom type (e.g. my_new_type) via the Custom Types API (POST /customtypes)
  2. Add the type to the routes array passed to createClient():
    { type: 'my_new_type', path: '/:uid' }
  3. Query any documents whose links reference the new type (e.g. client.getAllByType('some_existing_type') where documents contain Link fields pointing to my_new_type documents)

Expected behavior: The query succeeds. The new type is immediately available for route resolution.

Actual behavior: The query fails with:
Error: [Link resolver error] Unknown type
Declared type: my_new_type
Expected one of: [list of all previously existing types, but NOT the newly created one]

Workaround: Go to the Prismic UI, open the new custom type, make any change (or just save), and then the query succeeds. This suggests the CDN type registry is only refreshed after a UI-triggered save, not after an API-triggered creation.

Impact: This breaks CI/CD workflows where we sync custom types via the API before building. The sync step creates the type successfully, but the subsequent build fails because the CDN doesn't recognize it yet. We have to manually intervene in the UI after every new type creation, defeating the purpose of API-driven sync.

3

I can confirm I've run into the same issue. The manual UI save workaround works thanks!

Would love to see this fixed!

5

Hi everyone,

I am experiencing the exact same issue, and it is really, really annoying.

This completely breaks our CI/CD workflows. The whole point of using the Custom Types API is to automate our deployments. Right now, our sync step successfully creates the type via the API, but the build immediately fails afterward because the Route Resolver throws this Unknown type error.

Having to manually log into the Prismic UI just to hit "save" and force the CDN to refresh completely defeats the purpose of having an automated process. The API should trigger the same cache invalidation as the UI does.

Is there a fix planned for this soon? As it stands, it makes automating Custom Types almost unusable for us.

6

Yeah, but when you have to sync 20 repositories, it's just a real hassle !

8

Hello all,

In order for us to investigate, could you all share which repositories you are working from? Thank you!

@stephane.douzima.ext, can you confirm if you're doing anything else with the UI after creating the Custom Types API? Saving does not republish the API, so it must be something else, maybe with a document? Let me know.

9

Hi, and apologies for the long silence on this thread.
I’m only circling back to it now. In the meantime we found a workaround that fully unblocked us, so I wanted to share it in case it helps others hitting the same wall.

The root cause is exactly as described: the CDN’s known-types registry (exposed in the repository metadata at /api/v2) only refreshes when a UI action bumps the master ref. Pushing a type via the Custom Types API doesn’t bump it, so any routes
entry referencing that type fails validation with [Link resolver error] Unknown type until someone edits/saves in the UI.

Instead of waiting for Prismic to recognize the type, we made the client resilient: we filter the routes array against the types the repository actually knows right now, using the types field already returned by /api/v2. A route for a type that isn’t recognized yet is simply omitted, so the query never trips the resolver. It re-activates on its own once the type shows up in /api/v2 (i.e. after the ref is bumped), with no manual step.

  import * as prismic from '@prismicio/client';

  const baseRoutes: prismic.Route[] = [
    { type: 'homepage', path: '/' },
    { type: 'page', path: '/:uid' },
    { type: 'my_new_type', path: '/new/:uid' }, // safe to add immediately
    // ...
  ];

  // The repository metadata lists the types known at the current master ref.
  async function getKnownTypes(repositoryName: string): Promise<Set<string>> {
    const res = await fetch(`https://${repositoryName}.cdn.prismic.io/api/v2`, {
      // cache as you see fit; types change rarely
      next: { revalidate: 3600 },
    });
    const { types } = await res.json();
    return new Set(Object.keys(types));
  }

  export async function createClient(repositoryName: string) {
    const known = await getKnownTypes(repositoryName);
    const routes = baseRoutes.filter((r) => known.has(r.type)); // drop unknown-type routes

    return prismic.createClient(repositoryName, { routes });
  }

Why this fixes the CI/CD pain specifically:

  • You can add the new type to your code/routes in the same change as the Custom Types API sync, the build won’t break even if the type isn’t recognized on every repository yet.
  • It’s safe in a multi-repository setup where a given type may exist on some repos but not others (each build only declares the routes its own repo knows).
  • The new type’s routing turns on automatically once it’s recognized (after the first publish / ref bump), so no manual “open and save in the UI” step.

Trade-off to be aware of: until the type is recognized, links to its documents won’t be resolved by the route resolver, but since there’s no published content for a brand-new type yet, that’s a non-issue in practice.

This would still be much cleaner if the Custom Types API bumped the registry directly, so the underlying request to Prismic stands but the above unblocked our automated builds completely.