heygen-com/hyperframes · error · Error

[s3Transport] upload source missing: ${localPath}

Error message

[s3Transport] upload source missing: ${localPath}

What it means

Thrown by `uploadFileToS3` when the local file at `localPath` does not exist (`!existsSync`). The transport refuses to issue a `PutObjectCommand` for a missing source because the SDK would otherwise fail later with a less actionable error and a half-initialized upload.

Source

Thrown at packages/aws-lambda/src/s3Transport.ts:118

    throw error;
  }
}

/**
 * Upload a local file's contents to an S3 URI using a streaming
 * `PutObjectCommand`. PutObject's 5 GB cap comfortably exceeds the
 * distributed pipeline's 2 GB planDir limit and the typical
 * chunk size (≤ 200 MB), so a single PUT works for every artifact this
 * adapter handles.
 */
export async function uploadFileToS3(
  client: S3Client,
  localPath: string,
  uri: string,
  contentType?: string,
): Promise<void> {
  if (!existsSync(localPath)) {
    throw new Error(`[s3Transport] upload source missing: ${localPath}`);
  }
  const { bucket, key } = parseS3Uri(uri);
  const size = statSync(localPath).size;
  await client.send(
    new PutObjectCommand({
      Bucket: bucket,
      Key: key,
      Body: createReadStream(localPath),
      ContentType: contentType,
      ContentLength: size,
    }),
  );
}

/**
 * Upload one content-addressed plan-v2 artifact exactly once.
 *
 * Existing objects are reused only when their immutable digest metadata and

View on GitHub (pinned to c2996c8626)

Solutions

1. Verify the file exists at `localPath` (absolute path preferred) before calling `uploadFileToS3`.
2. Ensure the producing step succeeded and wrote to the exact same path.
3. Use `resolve()`/absolute paths to avoid working-directory ambiguity in Lambda.
4. Delay cleanup of render output until after the upload completes.

Example fix

// before: relative path, wrong cwd
await uploadFileToS3(s3, "out/render.mp4", uri);
// after: absolute, verified
const abs = join(workDir, "out/render.mp4");
if (!existsSync(abs)) throw new Error(`render output missing: ${abs}`);
await uploadFileToS3(s3, abs, uri);

import { existsSync } from "node:fs";
import { resolve } from "node:path";
function assertUploadSourceExists(localPath: string): string {
  const abs = resolve(localPath);
  if (!existsSync(abs)) {
    throw new Error(`upload source missing: ${abs}`);
  }
  return abs;
}
// call before uploadFileToS3

When it happens

Trigger: Calling `uploadFileToS3(client, localPath, uri)` where `localPath` does not point to an existing file on disk.

Common situations: Render output written to a different path than the upload call; a prior step failed to produce the file but did not throw; relative path resolved against the wrong working directory; file was cleaned up by a concurrent process before upload.

Related errors

• [s3Transport] expected s3:// URI, got: ${JSON.stringify(uri)
• [s3Transport] missing key in s3 URI: ${JSON.stringify(uri)}
• [s3Transport] empty bucket or key in s3 URI: ${JSON.stringif
• [s3Transport] s3 GetObject returned empty body for ${uri}
• [deploySite] projectDir is not a directory: ${opts.projectDi

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/b031291810a72683. Report an issue: GitHub.