Skip to content

union-circular

Id
@azure-tools/typespec-client-generator-core/union-circular

Severity: warning

This diagnostic is issued when TCGC converts a union that directly or indirectly contains itself. Recursive union shapes cannot be represented safely as generated SDK union types.

Impact

Section titled “Impact”
  • Area: SDK union type conversion. Generation continues with a fallback union shape, but the recursive union cannot become a usable SDK union.
  • Not affected: The TypeSpec union declaration is still accepted by the compiler.

❌ Incorrect Usage

Section titled “❌ Incorrect Usage”
@service
namespace Test {
  union Test {
    null,
    Test, // union contains itself
  }


  op test(test: Test): void;
}

Diagnostic Message

Section titled “Diagnostic Message”

TCGC reports:

Cannot have a union containing self.

✅ How to Fix

Section titled “✅ How to Fix”

Break the circular union reference or model the recursive relationship through a model property instead.

@service
namespace Test {
  union Test {
    null,
    string,
  }


  op test(test: Test): void;
}

Suppression

Section titled “Suppression”

This diagnostic should not be suppressed. Fix the spec to break the circular union reference, or model the recursion through a model property instead.