apache/beam · error · Error

not found. Please build the server with cd ; ./gradlew )

Error message

${localPath} not found. Please build the server with
      cd ${projectRoot}; ./gradlew ${gradleTarget})

What it means

When the configured Beam version is a SNAPSHOT, gradleToJar expects a locally built jar (from a Gradle snapshot build) to exist at localPath. If the file does not exist, it throws with build instructions rather than falling back to Maven, because SNAPSHOT artifacts are not published to Maven Central.

Solutions

1. Build the server: `cd <projectRoot> && ./gradlew <gradleTarget>` (as stated in the message).
2. Switch to a released (non-SNAPSHOT) Beam version so the jar is fetched from Maven.
3. Verify localPath points at the actual jar location produced by the Gradle build.
4. Set the project root configuration so the snapshot path resolves correctly.

Example fix

// before: snapshot version with no local build
version = "2.61.0-SNAPSHOT";

// after: either build it
cd beam && ./gradlew :runners:portable:java:...  // per gradleTarget
// or pin a release
version = "2.60.0";

import fs from 'fs';
if (version.includes('SNAPSHOT') && !fs.existsSync(localPath)) {
  throw new Error(`Build snapshot jar first: cd ${projectRoot}; ./gradlew ${gradleTarget}`);
}

try {
  jar = await gradleToJar(...);
} catch (e) {
  if (/not found\. Please build the server/.test(String(e))) {
    // fall back to a released version
    jar = JavaJarService.mavenJarUrl(artifactId, releaseVersion);
  } else throw e;
}

When it happens

Trigger: Using a 'SNAPSHOT' Beam version while the local Gradle-built server jar is absent at the expected path — e.g. pointing at a snapshot version without running `./gradlew <gradleTarget>` in the Beam project root.

Common situations: Developers tracking Beam master/SNAPSHOT who checked out the repo but never built the Java server; stale build output after switching versions; CI environments without the Gradle build step.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Could not find the provided transforms config source
• Aborted with error
• Artifacts not found at location
• BigQueryMetastoreCatalog doesn't support Java 8
• Can't find a Python executable.

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/a308a7f900979394. Report an issue: GitHub.

Appendix: source

Thrown at sdks/typescript/src/apache_beam/utils/service.ts:318

          "build",
          "libs",
          JavaJarService.jarName(
            artifactId,
            version.replace("-SNAPSHOT", ""),
            "SNAPSHOT",
            appendix,
          ),
        );

    if (version.includes("SNAPSHOT") && !projectRoot) {
      version = "latest";
    }

    if (localPath && fs.existsSync(localPath)) {
      console.info("Using pre-built snapshot at", localPath);
      return localPath;
    } else if (version.includes("SNAPSHOT")) {
      throw new Error(
        `${localPath} not found. Please build the server with
      cd ${projectRoot}; ./gradlew ${gradleTarget})`,
      );
    } else {
      return JavaJarService.mavenJarUrl(
        artifactId,
        version,
        undefined,
        appendix,
      );
    }
  }

  static async mavenJarUrl(
    artifactId: string,
    version: string,
    classifier: string | undefined = undefined,
    appendix: string | undefined = undefined,

View on GitHub (pinned to 12126d8942)