What causes "[s3Transport] missing key in s3 URI: ${JSON.stringify(uri)}" in heygen-com/hyperframes?

Append the object key to the URI: `s3://bucket/path/to/object`.

heygen-com/hyperframes · error · Error

[s3Transport] missing key in s3 URI: ${JSON.stringify(uri)}

Error message

[s3Transport] missing key in s3 URI: ${JSON.stringify(uri)}

What it means

Thrown by `parseS3Uri` when the URI starts with `s3://` but contains no slash after the bucket — i.e. it specifies a bucket with no key. S3 objects require both a bucket and a non-empty key; a bare `s3://bucket` cannot address an object.

Source

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

  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}`;
}

/** Stream an S3 object to a local file path. Throws if the body is missing. */
export async function downloadS3ObjectToFile(
  client: S3Client,
  uri: string,

View on GitHub (pinned to c2996c8626)

Solutions

Append the object key to the URI: `s3://bucket/path/to/object`.
If you meant the bucket as a location, build a URI with at least one key segment.
Validate config at load time with `parseS3Uri` in a try/catch to surface bad values early.

Example fix

// before
parseS3Uri(process.env.HF_OUTPUT_BUCKET); // "s3://my-bucket"
// after
parseS3Uri(`${process.env.HF_OUTPUT_BUCKET}/renders/${renderId}/out.mp4`);

Defensive patterns

Strategy: validation

Validate before calling

function assertHasKey(uri: string): void {
  const rest = uri.slice("s3://".length);
  if (!rest.includes("/")) {
    throw new Error(`s3 URI is missing a key: ${uri}`);
  }
}

Type guard

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

Prevention

Build URIs from `{bucket, key}` via formatS3Uri so a missing key surfaces as undefined input.
Always pair a bucket config with an explicit key template.
Unit-test config values with the same parser the transport uses.

When it happens

Trigger: Calling `parseS3Uri("s3://my-bucket")` — the portion after `s3://` has no `/`, so there is no key.

Common situations: Configured only a bucket name where a full object path was expected; trailing path stripped by a bad string split; env var set to the bucket root rather than a specific object key.

Related errors

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