Java SDK Generation Pipeline Troubleshooting Guide

August 4, 2026 · View on GitHub

This guide helps you identify which category a pipeline failure belongs to and apply the solution.

Applies to: Java SDK generation pipeline (spec PR validation / spec PR generation)

Related: SDK Validation FAQ | SDK Generation Pipelines | SDK Release Pipeline | Language - Java Teams channel

Quick Triage

Find the most specific signal in the failure log and jump directly:

Log SignalCategoryJump
[COMPILE] Maven build fail. + Checkstyle PackageName must match patterntspconfig1.1 Namespace Segment Too Long
not supported by Fluent Premiumtspconfig1.2 Unsupported Emitter Option (Fluent Premium)
Verify TypeSpec Code Generation check failstspconfig1.3 Verify TypeSpec Code Generation fails
[COMPILE] Maven build fail. + customization class/method referencedcustomization2. Customization Errors
Could not resolve dependencies / Could not transfer artifactintermittent3.1 Maven Dependency Download Failure
None matchunknownEscalation

1. tspconfig Errors

How to identify: The error message contains [VALIDATE][tspconfig.yaml] or [GENERATE] ..., or generation output lands in the wrong directory.

References:

1.1 Namespace Segment Too Long

Log signal:

  • [COMPILE] Maven build fail.
  • Checkstyle PackageName error with must match pattern

Error (real-world example):

[ERROR] Name 'com.azure.resourcemanager.<verylongsegment>...' must match pattern
'^(?=.{9,80}$)((com.microsoft|com.azure)(\.[a-z][a-z0-9]{1,31})*)+$'. [PackageName]
[ERROR] Failed to execute goal ... maven-checkstyle-plugin ... There are N errors reported by Checkstyle

Root cause: The namespace does not match the repository's Checkstyle PackageName rule.

Solution:

  1. Check whether the namespace is approved. If the long namespace has been reviewed and approved (e.g. it matches the service name exactly):
  2. If the namespace is not approved, rename or shorten the namespace until it matches the PackageName rule shown in the error log. In practice, check the generated package name against the regex and reduce any part of the namespace that causes the mismatch, such as an overly long segment or an overall package name that is too long.

1.2 Unsupported Emitter Option (Fluent Premium)

Log signal:

  • not supported by Fluent Premium

Error (real-world example):

error @azure-tools/typespec-java/generator-error: ... - Unhandled error.
java.lang.IllegalStateException: Package 'com.azure.resourcemanager.<pkg>' is not supported by Fluent Premium

Root cause: tspconfig.yaml enables an emitter option (for example premium: true) that is not supported for the target package.

Solution: Remove the unsupported option from options.@azure-tools/typespec-java.

1.3 Verify TypeSpec Code Generation fails

Log signal:

  • Verify TypeSpec Code Generation check fails in Java SDK CI - java-pullrequest

Error (real-world example):

Exception: /mnt/vss/_work/1/s/eng/scripts/Compare-CurrentToCodegeneration.ps1:225
Line |
 225 |  $job | Receive-Job 2>$null | Out-Null
     |  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | ScriptHalted

##[error]PowerShell exited with code '1'.

Root cause: The Verify TypeSpec Code Generation step in the Java SDK PR pipeline re-runs code generation using repository-local configuration and compares regenerated output with committed code. This check usually fails because regeneration produces large diffs. Common causes include:

  • tspconfig.yaml has incorrect Java emitter settings.
  • In tspconfig.yaml, api-version changes can directly change operation/model counts.
  • In tspconfig.yaml, enable-sync-stack changes can add or remove a large set of sync client classes.
  • In tspconfig.yaml, flavor changes (for example, azure vs standard) change generated code style and shape.

When operation counts change significantly, api-version drift is the most common cause. If api-version is not explicitly fixed in tspconfig.yaml, it may default to the latest version, which can differ from the version used when the checked-in SDK was originally generated.

Solution:

  1. Check the pipeline code-generation diff, re-run local generation with the same repository configuration, compare against the SDK output in the generated PR, and update the relevant tspconfig.yaml settings (for example api-version, enable-sync-stack, flavor).
  2. Update tspconfig.yaml in the spec repo PR, commit the change, and rerun generation to regenerate the SDK PR.

Example (API version mismatch): pin api-version in tspconfig.yaml so the Verify step and SDK generation use the same version, then rerun generation.

options:
  "@azure-tools/typespec-java":
    api-version: "2025-12-01"   # ✅ pin the api-version used for generation

2. Customization Errors

How to identify: [COMPILE] Maven build fail. with Java compilation errors referencing hand-written classes/methods that no longer exist in generated code. The pipeline may auto-retry with customization disabled and show:

Generate a fresh package from TypeSpec. If there was prior customization on the package,
please check whether it causes failure, and fix them before apiview.

Background: Azure SDK packages usually contain both generated code (auto-produced from TypeSpec) and customization code (hand-written by SDK developers):

  • generated code: produced by the generator; API surface may change when the spec or generator changes, which can break compilation.
  • customization code: maintained by SDK developers; commonly wired via customization-class and preserved during regeneration with partial-update: true.

Reference: TypeSpec Java Customization

Prerequisites for customization: When adding customization code, two options must be set in tspconfig.yaml:

options:
  "@azure-tools/typespec-java":
    customization-class: "com.azure.resourcemanager.yourservice.customization"
    partial-update: true
  • customization-class — the Java package containing your hand-written customization classes
  • partial-update — set to true so the generator preserves your custom files instead of overwriting the entire output directory

3. Intermittent Errors

How to identify: The failure is in dependency download, npm install, or CI infrastructure — not in generation/compilation logic. Error messages mention network timeouts, Could not resolve dependencies, Could not transfer artifact, or failures in injected DevOps tasks.

Solution for all intermittent errors: Re-run the pipeline.

If failure persists after 2-3 retries, it is likely a genuine issue, not intermittent. Review the error details and consult sections 1 or 2 above.

3.1 Maven Dependency Download Failure

Error: [COMPILE] Maven build fail. with Could not resolve dependencies / Could not transfer artifact / connection timeout.

Error (real-world example):

[FATAL] Non-resolvable parent POM for com.azure:customization-loader:1.0.0-beta.1:
Could not transfer artifact ... from/to central (https://repo.maven.apache.org/maven2):
Connect to repo.maven.apache.org:443 ... failed: Network is unreachable (connect failed)
and 'parent.relativePath' points at wrong local POM

Escalation

If the issue persists after following this guide, post in the Language - Java Teams channel with:

  • Spec PR link
  • Pipeline build link and build ID
  • Exact error message
  • What you've already tried

Other resources: TypeSpec GitHub | Troubleshoot PR failures | SDK support