Server functions and non-server functions in the same file: Failed to resolve import "tanstack-start-injected-head-scripts:v"

[ulrichstark]

Which project does this relate to?

Start

Describe the bug

I'm declaring server functions and non-server functions in the same file. The non-server functions call other functions only meant to be executed on the server (like getCookies of @tanstack/react-start/server). That's okay because these non-server functions are wrapped by server functions outside of this file.

If I have a route that uses one of the server function of this file as loader, the route fails to load because of the other unused but still included non-server function of the imported file.

Error message:

[plugin:vite:import-analysis] Failed to resolve import "tanstack-start-injected-head-scripts:v" from "node_modules/@tanstack/start-server-core/dist/esm/loadVirtualModule.js?v=4239e47c". Does the file exist?

index.tsx route:

import { usedServerFunction } from "../functions";
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/")({
    loader: async () => usedServerFunction(),
    component: RouteComponent,
});

function RouteComponent() {
    const message = Route.useLoaderData();

    return <h1>{message}</h1>;
}

functions.tsx file:

import { createServerFn } from "@tanstack/react-start";
import { getCookies } from "@tanstack/react-start/server";

export const usedServerFunction = createServerFn().handler(() => {
    return "Hello World!";
});

function unusedFunction() {
    getCookies();
}

Your Example Website or App

https://github.com/ulrichstark/tanstack-repro-failed-to-resolve-import-tanstack-start-injected-head-scripts

Steps to Reproduce the Bug or Issue

git clone https://github.com/ulrichstark/tanstack-repro-failed-to-resolve-import-tanstack-start-injected-head-scripts
cd tanstack-repro-failed-to-resolve-import-tanstack-start-injected-head-scripts
npm install
npx vite

Expected behavior

No error

Screenshots or Videos

Platform

• Router / Start Version: 1.134.3
• OS: macOS
• Browser: Chrome
• Browser Version: 141
• Bundler: Vite
• Bundler Version: 7.1.12

Additional context

The error is gone when removing unusedFunction or commenting out the call to getCookies.
Maybe similar to #5673 and #2783.

[schiller-manuel]

this is not a bug. when start compiles server functions for the client, it removes the handler and then performs dead code elimination to remove all the "things" (i.e. imports, variable declarations, function declarations) that were referenced inside the handler.
dead code elimination does ONLY touch "things" that were referenced BEFORE compilation.

conceptually, this looks like this:

input

import { createServerFn } from "@tanstack/react-start";
import { getCookies } from "@tanstack/react-start/server";

export const usedServerFunction = createServerFn().handler(() => {
    return "Hello World!";
});

function unusedFunction() {
    getCookies();
}

after server function compilation for the client:

import { createServerFn } from "@tanstack/react-start";
import { getCookies } from "@tanstack/react-start/server";

export const usedServerFunction = createClientRpc('some-id')

function unusedFunction() {
    getCookies();
}

since unusedFunction was not referenced by the server function handler, it wont be removed by the compiler.

however, if you had this

import { createServerFn } from "@tanstack/react-start";
import { getCookies } from "@tanstack/react-start/server";

export const usedServerFunction = createServerFn().handler(() => {
	usedFunction()
    return "Hello World!";
});

function usedFunction() {
    getCookies();
}

the (conceptual) result would be:

import { createServerFn } from "@tanstack/react-start";

export const usedServerFunction = createClientRpc('some-id')

[ulrichstark]

Okay understood, thank you very much @schiller-manuel for taking your time to explain that.

But is it really expected behavior that the application crashes with that cryptic error message without pointing to what and where it might went wrong?

And If we still want to organize server code, some wrapped with createServerFn and some not, in the same file, what should we do? Wrap every function with createServerFn? Or probably better wrap with createServerOnlyFn if not already wrapped with createServerFn? Or is there a third option that allows me to avoid the error but still organize all this similar logic in one file cleanly?

[omergulcicek]

#5196 (comment)

I’ve encountered the same issue and done a deep dive into why this happens. It usually stems from the server/client boundary being blurred (e.g., importing server-only utilities like Supabase or DB clients into files that end up in the client bundle).

I wrote a detailed guide on how to resolve this by properly separating your server logic and using createServerFn correctly to avoid these virtual module resolution errors.

You can check out the solution here: TanStack Start: Resolving the tanstack-start-injected-head-scripts Error

Hope it helps anyone else stuck on this!