Troubleshooting

vite build or vite dev can't fetch the manifest

Check. Read the message. The consentManifest plugin downloads the manifest once per build, and in vite dev the first time the server loads it. When the download fails or takes longer than 10 seconds, vite build stops with an error that starts with @c15t/tanstack-start/build: could not fetch the consent manifest from <url> during the build. vite dev logs the same message as a warning and keeps going. snapshot from c15t/generated is then undefined, so the server fetches the policy at runtime.

snapshot is undefined

Check. Log snapshot from c15t/generated in the server function. In the browser bundle it is always undefined: the plugin keeps the policy on the server. On the server, it is undefined when Vite had no policy to serve: consentManifest is missing from plugins in vite.config.ts, the fetch failed in vite dev or in a build with C15T_ON_BUILD_ERROR=runtime, or the backend URL is relative.

Fix. createConsentStateHandler and createConsentRoute read the snapshot themselves, so most apps never import it. On the server, add the plugin or fix the fetch error, then restart vite dev or rebuild. While snapshot is undefined, the server fetches and caches the policy at runtime.

The banner is not in the server HTML

Check. View the page source under a policy that asks for a choice. Look for data-testid="consent-banner-root".

The server function fails to resolve at runtime

Check. Find where you call createServerFn(). Start's compiler identifies each server function by the file and the top-level assignment where you call it, so a call inside a package, a function or a conditional fails.

Fix. Declare const getConsentState = createServerFn(...).handler(createConsentStateHandler()) at the top level of your own route module, as in the quickstart.

A serialization error mentions a function

Check. Look at what your server functions and loaders return. Something with functions in it, such as vendor script configurations or a hosted() transport from c15t/react, cannot be serialized. hosted() from c15t/tanstack-start is plain data and can be returned.

Fix. Return only the consent state from the server function. Import scripts in the root route module and pass them to ConsentRoot there.

The same-origin setup never renders the banner on the server

Check. Look at the backendURL you pass to createConsentStateHandler, or VITE_C15T_BACKEND_URL. When it is /api/c15t, the helper skips the fetch and returns only the cookie and header state, because a server that fetches its own route during a render can stall.

Fix. Keep VITE_C15T_BACKEND_URL absolute, and don't pass backendURL: '/api/c15t'. To send the browser's requests through the route, pass routePrefix: '/api/c15t' and proxy: true to createConsentStateHandler instead.

Saves through /api/c15t fail with 403 or a challenge page

Check. The backend's firewall blocks the proxied POST /subjects. A server cannot solve a browser challenge, such as Vercel Attack Challenge Mode or Cloudflare Super Bot Fight Mode.

Fix. Exempt the consent paths from the challenge. Requests from the route carry an x-c15t-proxy: @c15t/tanstack-start header you can match in a firewall rule. If rate limits treat every visitor as one IP address, and your host overwrites x-forwarded-for, set trustForwardedHeaders: true on createConsentRoute.

The browser calls /api/c15t/init and gets a 404

Check. ConsentRoot calls /api/c15t/init only when the state carries routePrefix: '/api/c15t', from createConsentStateHandler. Confirm that the app mounts the consent route at src/routes/api/c15t/$.ts.

Fix. Mount the same-origin route, or remove routePrefix, so the browser calls your backend directly. Earlier alphas sent init to /api/c15t/init by default; now there is no default.

ConsentRoot throws that it needs a backend URL

Check. The page throws one of these errors from ConsentRoot:

• c15t: manifest() needs a backend URL. Set `backendURL` in your config.
• c15t: hosted() needs a backend URL. Set `backendURL` on the mode or in your config.

The state names no backend URL and consentManifest() supplied none, for example on a page with state={{}} and no plugin in vite.config.ts.

Fix. Add consentManifest() to vite.config.ts and set VITE_C15T_BACKEND_URL (or VITE_INTH_PROJECT_URL). Earlier alphas fell back to offline mode here; now the root throws. To run without a backend, pass mode: offline() to createConsentStateHandler, or state={{ mode: offline() }}.

A vendor loads before the visitor chooses

Check. Search route head() definitions, your root component and any tag manager for the vendor's script or SDK initializer.

Fix. Remove every loader except the one in ConsentRoot's scripts. c15t only gates scripts registered with it. Scripts and embeds covers the options.

The page throws that no IABProvider is mounted

The visitor's policy uses the iab model and the backend sent its vendor list, but no IABProvider is mounted. The standard banner and dialog do not handle the IAB model, so they throw rather than leave the visitor with no consent UI. Server and browser render the same error.

Fix it one of two ways:

• If the site uses IAB TCF, render IABProvider with IABConsentBanner and IABConsentDialog from c15t/react/iab inside your consent provider. They can sit next to the standard banner.
• If it does not, remove the iab model from the policy for that region in your Inth project or policy pack.

A backend that answers gvl: null turns IAB off for that request. The policy then runs as opt-in and nothing throws.

The check passes once c15t/react/iab has loaded. If you import the IAB components with a dynamic import(), a render of the standard banner that happens before the import finishes still throws.

Inspect the active policy

Render this component inside ConsentRoot. It reads state and records no choice:

import { useSnapshot } from 'c15t/tanstack-start';

export function ConsentPolicyDebug() {
	const snapshot = useSnapshot();
	const resolution = snapshot.resolution;

	return (
		<pre>
			{JSON.stringify(
				{
					status: resolution.status,
					policy: resolution.status === 'matched' ? resolution.policy.id : null,
					prompt: snapshot.promptRequirement,
					location: snapshot.location,
				},
				null,
				2
			)}
		</pre>
	);
}

location shows the country and region the server resolved. Remove the component after you finish.

Names from an earlier alpha are missing

Check. TypeScript or the build reports a missing export or option, such as createConsentServerRoute, DEFAULT_INIT_ROUTE or ConsentRoot's backendURL prop. The v3 alphas removed names that never shipped in a stable release, with no alias.

Fix. Use the current names:

The renames shared by every framework:

Frame and its parts still work, with a one-time warning outside production. Use ConsentGate instead.

More help

Troubleshoot consent covers problems shared by every framework, such as a missing banner, analytics that load before a choice, imports that fail because npm installed c15t v2, choices that disappear on reload, server HTML that differs from the browser, static builds that fail and content blockers that hide the consent UI.