sveltejs/kit · error

Cannot call ' .withOverride()' on the server

Error message

Cannot call '${__.name}.withOverride()' on the server

What it means

Runtime guard on a server-side query resource: withOverride() is a client-only method that lets browser code override query state (e.g. after a mutation). Server-side query resources return live promises, not reactive state, so the method is replaced by this throwing stub.

Solutions

1. Move withOverride usage behind an if (browser) check or into client-only test code
2. Use server-side dependency injection (mock the query implementation itself) for server tests
3. Guard with import.meta.env.DEV and avoid overriding in SSR paths

Example fix

// before
const resource = getPosts.resource();
resource.withOverride(mockData); // throws on server
// after
if (browser) {
  getPosts.resource().withOverride(mockData);
}

import { browser } from '$app/environment';
if (!browser) throw new Error('withOverride is client-only');

function canOverride(res) {
  return typeof res === 'object' && res !== null && typeof res.withOverride === 'function' && browser;
}

if (browser) {
  resource.withOverride(mock);
} else {
  // server: skip override
}

When it happens

Trigger: Calling .withOverride() on a query resource (created via prerender/parse of a query resource) in server-side code, e.g. in a load function, server hook, or during SSR.

Common situations: Reusing client test helpers that mock queries with withOverride in universal code executed on the server; accidentally importing test-only utilities into production code.

Related errors

• Cannot access event.
• Cannot call query ' ' while prerendering, as prerendered…
• ${prerendered.error}
• Query resolved without a value
• requested(...) expects a query function created with…

AI-assisted analysis of sveltejs/kit@03f1687fe6 (2026-09-02). Data as JSON: /api/errors/312b994e05883400. Report an issue: GitHub.

Appendix: source

Thrown at packages/kit/src/runtime/app/server/remote/query.js:499

			delete get_cache(__, state)[payload];

			refresh(event, state, __, payload, get_promise);

			return Promise.resolve();
		},
		/** @param {any} value */
		set(value) {
			const p = (promise = Promise.resolve(value));
			get_cache(__, state)[payload] = p;

			refresh(event, state, __, payload, () => p);
		},
		/** @type {Promise<any>['then']} */
		then(onfulfilled, onrejected) {
			return get_promise().then(onfulfilled, onrejected);
		},
		withOverride() {
			throw new Error(`Cannot call '${__.name}.withOverride()' on the server`);
		},
		get [Symbol.toStringTag]() {
			return 'QueryResource';
		}
	};
}

/**
 * @param {RemoteQueryLiveInternals} __
 * @param {string} payload — the stringified raw argument (i.e. the cache key the client will use)
 * @param {RequestEvent} event
 * @param {RequestState} state
 * @param {() => AsyncGenerator<any, void, void>} get_generator
 * @returns {RemoteLiveQuery<any>}
 */
function create_live_query_resource(__, payload, event, state, get_generator) {
	/** @type {Promise<any> | null} */
	let promise = null;

View on GitHub (pinned to 03f1687fe6)