Skip to main content

PKU431: Schema Has No Root

Error Message​

[PKU431] Error generating schema since it has no root: [TypeName]

What Went Wrong​

The TypeScript type couldn't be converted to a JSON schema because it doesn't have a clear root definition. This typically happens with certain TypeScript utility types or overly complex type manipulations.

Common Causes​

  1. Circular type references
  2. Type aliases that are too generic
  3. Utility types without concrete implementations
  4. Types that reference non-exported types

How to Fix​

Option 1: Simplify the Type​

// ❌ Problematic
type MyType = Partial<Record<string, unknown>>

// ✅ Better
interface MyType {
  [key: string]: string | number | boolean
}

Option 2: Use Interface Instead of Type Alias​

// ❌ May cause issues
export type User = {
  name: string
  email: string
}

// ✅ More reliable for schema generation
export interface User {
  name: string
  email: string
}

Option 3: Provide Concrete Implementation​

// ❌ Too generic
type Handler<T> = (input: T) => Promise<T>

// ✅ Concrete type
interface CreateUserInput {
  name: string
  email: string
}

interface CreateUserOutput {
  id: string
  name: string
  email: string
}

Workaround​

If you can't modify the type, you can exclude it from schema generation by not using it as a function input/output type, or by using a simpler type for the function signature.

  • PKU456 - Schema Generation Error