client-location-conflict

Id

@azure-tools/typespec-client-generator-core/client-location-conflict

Severity: warning

This diagnostic is issued when a @clientLocation move conflicts with the client structure TCGC is building. It is reported in several situations:

• String target with multiple root clients — a string target cannot be resolved when more than one root client exists, because TCGC cannot decide which root client should own the new sub client.
• Moving an operation onto another operation — an operation can only be moved to an interface or namespace, not onto another operation.
• Moving a model property to a string target — a model property can only be moved to an interface or namespace, not to a string-named target.
• Parameter name already used in client initialization — the parameter produced by the moved model property collides with an existing client initialization parameter.
• Same parameter moved with different types — the same parameter name is moved to one client with conflicting types, which commonly happens when @clientLocation is applied to a templated parameter that is instantiated with different types.

Impact

• Area: Client operation and parameter placement. Generation continues, but the requested @clientLocation move cannot be applied safely to the generated client structure.
• Not affected: HTTP routes, parameter wire names, and service operation definitions are unchanged.

String target with multiple root clients

Diagnostic Message

TCGC reports:

@clientLocation with string target could not be used for multiple root clients scenario

✅ How to Fix

Use an interface or namespace target when multiple root clients exist, or define the target sub client explicitly under the intended root client.

Operation to operation

Diagnostic Message

TCGC reports:

`@clientLocation` cannot be used to move an operation to another operation. Operations can only be moved to interfaces or namespaces.

✅ How to Fix

Move the operation to an interface or namespace instead of another operation.

Model property conflicts with client initialization

❌ Incorrect Usage

model ClientOptions {
  apiKey: string;
}

@clientInitialization(ClientOptions)
@service
namespace WidgetService {
  model Widget {
    @clientLocation(WidgetService) // conflicts with `apiKey` already in the client initialization model
    apiKey: string;
  }
}

Diagnostic Message

TCGC reports:

There is already a parameter called 'apiKey' in the client initialization.

✅ How to Fix

Rename the moved property or the client-initialization parameter so they do not collide.

model ClientOptions {
  apiKey: string;
}

@clientInitialization(ClientOptions)
@service
namespace WidgetService {
  model Widget {
    @clientLocation(WidgetService)
    widgetApiKey: string;
  }
}

Model property moved to string target

❌ Incorrect Usage

@service
namespace WidgetService {
  model Widget {
    @clientLocation("SharedClient") // a model property can only be moved to an interface or namespace, not a string target
    region: string;
  }
}

Diagnostic Message

TCGC reports:

`@clientLocation` can only move model properties to interfaces or namespaces.

✅ How to Fix

Move the model property to a concrete interface or namespace target instead of a string-named target.

@service
namespace WidgetService {
  namespace SharedClient {

  }

  model Widget {
    @clientLocation(SharedClient)
    region: string;
  }
}

Moved parameters with conflicting types

❌ Incorrect Usage

@service
namespace Default;

union FeatureOptInKeys {
  insights: "Insights.V1Preview",
  schedules: "Schedules.V1Preview",
}

alias WithPreviewHeader<T extends FeatureOptInKeys> = {
  @clientLocation(Default) // templated parameter moves different concrete types to the same client
  @header("x-preview-features")
  previewFeatures: T;
};

op getInsights(...WithPreviewHeader<FeatureOptInKeys.insights>): void;
op getSchedules(...WithPreviewHeader<FeatureOptInKeys.schedules>): void;

Diagnostic Message

TCGC reports:

@clientLocation cannot move multiple parameters named 'previewFeatures' with different types to the same client. This often happens when @clientLocation is applied to a templated parameter that is instantiated with different types. Move the parameter on each operation instead, so that it has a consistent type on the client.

✅ How to Fix

Move the parameter on each operation instead of on the templated alias, or ensure every moved previewFeatures parameter has the same type.

@service
namespace Default;

union FeatureOptInKeys {
  insights: "Insights.V1Preview",
  schedules: "Schedules.V1Preview",
}

op getInsights(
  @clientLocation(Default)
  @header("x-preview-features")
  previewFeatures: FeatureOptInKeys,
): void;

op getSchedules(
  @clientLocation(Default)
  @header("x-preview-features")
  previewFeatures: FeatureOptInKeys,
): void;

Suppression

This diagnostic should not be suppressed. Fix the @clientLocation usage as described in the cases above.