createServerFn handler encounters a type error when the return type contains a property of type unknown

[axuj]

Which project does this relate to?

Start

Describe the bug

When using createServerFn from @tanstack/start, a TypeScript error occurs if the handler's return type is an object that includes a property with the unknown type. The type inference seems to fail, causing a type mismatch error.

Your Example Website or App

https://tanstack.com/start/latest/docs/framework/react/server-functions#validation-with-zod

Steps to Reproduce the Bug or Issue

1. Define a type with a property of type unknown.
2. Create a server function using createServerFn.
3. In the .handler(), return an object that conforms to the defined type.

example code:

import { createServerFn } from '@tanstack/start';

type Res = {
  text: string;
  metaData: unknown;
};

const loader = createServerFn().handler(async () => {
  const res: Res = {
    text: 'hello',
    metaData: {
      tag: 'first',
    },
  };
  return res;
});

error message

Argument of type '() => Promise<Res>' is not assignable to parameter of type 'ServerFn<Register, Method, undefined, undefined, Res>'.
  Type 'Promise<Res>' is not assignable to type 'ServerFnReturnType<Register, Res>'.
    Type 'Promise<Res>' is not assignable to type 'Promise<{ text: string; metaData: {}; }>'.
      Type 'Res' is not assignable to type '{ text: string; metaData: {}; }'.
        Types of property 'metaData' are incompatible.
          Type 'unknown' is not assignable to type '{}'.ts(2345)

Expected behavior

Correct use of type

Screenshots or Videos

No response

Platform

• Router / Start Version: 1.132.6
• OS: Windows
• Browser: [e.g. Chrome, Safari, Firefox]
• Browser Version: [e.g. 91.1]
• Bundler: vite
• Bundler Version: 7.1.7

Additional context

No response

[majoncas-ue]

Looks like related to #5222

[schiller-manuel]

this is actually the desired behavior. we check whether the return type is serializable. if it is not, you will get an error.
for unknown we wont know so by default this will raise an error as well.
you can either correctly type your return type or type assert

[axuj]

this is actually the desired behavior. we check whether the return type is serializable. if it is not, you will get an error. for unknown we wont know so by default this will raise an error as well. you can either correctly type your return type or type assert

Many times we need to obtain complex but serializable types from other tools, such as UIMessage from Vercel AI SDK. Rewriting a clear type adds a lot of ineffective work.

[schiller-manuel]

@axuj UIMessage can be typed explicitly, doesnt this work? https://ai-sdk.dev/docs/ai-sdk-ui/message-metadata

[axuj]

@schiller-manuel Yes, even if UIMessage sets generics internally, it still uses unknown.

As a comparison, custom generics passing any won't cause errors.
I think unknown is too common, many libraries use it.

[nilsbunger]

@axuj UIMessage can be typed explicitly, doesnt this work? https://ai-sdk.dev/docs/ai-sdk-ui/message-metadata

@schiller-manuel your link probably solves the problem for the metadata part of the structure, but it doesn't solve the type error overall. There are unknowns embedded in another portion of the tool type ("dynamic-tool" gets added to the toolset we give it), and that part can't be specified from the outside.