heygen-com/hyperframes · error · Error

[s3Transport] expected s3:// URI, got: ${JSON.stringify(uri)

Error message

[s3Transport] expected s3:// URI, got: ${JSON.stringify(uri)}

What it means

Thrown by `parseS3Uri` when the input does not start with the `s3://` scheme. The transport layer only speaks `s3://` URIs; anything else (https, file, bare bucket) is rejected at the boundary before it reaches the S3 SDK.

Source

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

import { pipeline } from "node:stream/promises";
import {
  GetObjectCommand,
  HeadObjectCommand,
  PutObjectCommand,
  type S3Client,
} from "@aws-sdk/client-s3";
import * as tar from "tar";

/** Parsed `s3://bucket/key` URI. */
export interface S3Location {
  bucket: string;
  key: string;
}

/** Parse `s3://bucket/key/path` → `{ bucket, key }`. Throws on malformed input. */
export function parseS3Uri(uri: string): S3Location {
  if (!uri.startsWith("s3://")) {
    throw new Error(`[s3Transport] expected s3:// URI, got: ${JSON.stringify(uri)}`);
  }
  const rest = uri.slice("s3://".length);
  const slash = rest.indexOf("/");
  if (slash === -1) {
    throw new Error(`[s3Transport] missing key in s3 URI: ${JSON.stringify(uri)}`);
  }
  const bucket = rest.slice(0, slash);
  const key = rest.slice(slash + 1);
  if (!bucket || !key) {
    throw new Error(`[s3Transport] empty bucket or key in s3 URI: ${JSON.stringify(uri)}`);
  }
  return { bucket, key };
}

/** Build `s3://bucket/key` from a location. */
export function formatS3Uri(loc: S3Location): string {
  return `s3://${loc.bucket}/${loc.key}`;
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Use the `s3://bucket/key` form for all transport calls.
2. If your config stores ARNs or HTTPS URLs, convert them to `s3://` at the config boundary.
3. Use `formatS3Uri({bucket, key})` to construct URIs from parts instead of string concatenation.
4. Add a unit test that config values match `/^s3:\/\//`.

Example fix

// before
parseS3Uri("https://my-bucket.s3.amazonaws.com/key");
// after
parseS3Uri("s3://my-bucket/key");

function isS3Uri(value: unknown): value is string {
  return typeof value === "string" && value.startsWith("s3://");
}

function isS3Uri(value: unknown): value is string {
  return typeof value === "string" && value.startsWith("s3://");
}

When it happens

Trigger: Calling `parseS3Uri` (directly or via download/upload helpers) with a URI like `https://...`, `bucket/key`, or `arn:aws:s3:::...`.

Common situations: Passing an HTTPS S3 console URL where an `s3://` URI was expected; copy-pasting a bucket ARN; configuration loaded a path-style URL; missing scheme prefix after an env-var interpolation.

Related errors

• [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}
• [s3Transport] upload source missing: ${localPath}
• [deploySite] projectDir is not a directory: ${opts.projectDi

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