Skip to main content

PKU456: Schema Generation Error

Error Message​

[PKU456] Error generating schema: [TypeName]

What Went Wrong​

Pikku encountered an error while trying to convert a TypeScript type into a JSON schema. This can happen for various reasons related to complex or unsupported type constructs.

Common Causes​

  1. Unsupported TypeScript features
  2. Circular dependencies
  3. Type imports that can't be resolved
  4. Complex generic types
  5. Types using advanced type manipulation

How to Fix​

Check for Circular References​

// ❌ Problematic: Circular reference
interface Node {
  value: string
  children: Node[] // References itself
}

// ✅ Better: Use explicit type or simplify
interface TreeNode {
  value: string
  children: TreeNode[] | undefined
}

Simplify Complex Generics​

// ❌ Too complex
type DeepPartial<T> = T extends object
  ? { [P in keyof T]?: DeepPartial<T[P]> }
  : T

interface User {
  profile: DeepPartial<ProfileData>
}

// ✅ Simpler
interface UserProfile {
  name?: string
  email?: string
  settings?: {
    theme?: string
    language?: string
  }
}

interface User {
  profile: UserProfile
}

Ensure All Types Are Exported​

// ❌ Private type used in public interface
type PrivateType = { secret: string }

export interface PublicAPI {
  data: PrivateType // Won't work for schema generation
}

// ✅ Export all types used in public interfaces
export type SharedType = { secret: string }

export interface PublicAPI {
  data: SharedType
}

Debugging Steps​

  1. Check the type definition - Look at the type mentioned in the error
  2. Simplify step by step - Comment out complex parts to isolate the issue
  3. Use interfaces over types - Interfaces are more reliably converted to schemas
  4. Verify imports - Make sure all referenced types can be resolved

Workaround​

If the type can't be fixed, consider:

  • Using a simpler DTO (Data Transfer Object) for the function signature
  • Manually defining the JSON schema
  • Excluding the problematic function from type generation