heygen-com/hyperframes · error · Error

[lambda policies validate] usage: hyperframes lambda policie

Error message

[lambda policies validate] usage: hyperframes lambda policies validate <policy.json>

What it means

Thrown by the `policies validate` subcommand when no positional policy JSON path was supplied (args.inputPath is undefined). The validate verb needs exactly one argument — the path to the IAM policy JSON to check against the CLI's required-actions list. Without it there is nothing to validate, so the command prints usage and (in --json mode) emits a structured error instead of throwing.

Source

Thrown at packages/cli/src/commands/lambda/policies.ts:252

      const trust = buildRoleTrustPolicy();
      const inline = buildPolicyDocument();
      const wrapped = {
        TrustRelationship: trust,
        InlinePolicy: inline,
      };
      console.log(JSON.stringify(wrapped, null, 2));
      return;
    }
    case "validate": {
      if (!args.inputPath) {
        const msg =
          "[lambda policies validate] usage: hyperframes lambda policies validate <policy.json>";
        if (args.json) {
          console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
          setCommandExitCode(1);
          return;
        }
        throw new Error(msg);
      }
      let result: ValidateResult;
      try {
        result = validatePolicy(args.inputPath);
      } catch (err) {
        const msg = normalizeErrorMessage(err);
        if (args.json) {
          console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
          setCommandExitCode(1);
          return;
        }
        console.error(c.error(`Failed to validate ${args.inputPath}: ${msg}`));
        setCommandExitCode(1);
        return;
      }
      if (args.json) {
        console.log(JSON.stringify({ ok: result.missing.length === 0, ...result }, null, 2));
        if (result.missing.length > 0) setCommandExitCode(1);

View on GitHub (pinned to c2996c8626)

Solutions

Add the policy JSON path as a positional: `hyperframes lambda policies validate ./infra/iam/hyperframes.json`.
If you want machine-readable output, add `--json`: it returns `{ok:false,error:...}` with exit code 1 instead of throwing.
Run `hyperframes lambda policies user` first to see the canonical required policy, then validate your file against it.

Example fix

# before
hyperframes lambda policies validate
# after
hyperframes lambda policies validate ./infra/iam/hyperframes.json

Defensive patterns

Strategy: validation

Validate before calling

// Ensure a policy path is present before calling policies validate
function assertPolicyPath(extra?: string): string {
  if (!extra) throw new Error("usage: hyperframes lambda policies validate <policy.json>");
  return extra;
}

Type guard

function isPolicyPath(v: unknown): v is string {
  return typeof v === "string" && v.trim() !== "";
}

Try / catch

try {
  await runPolicies({ verb: "validate", inputPath, json: true });
} catch (err) {
  if (/usage: hyperframes lambda policies validate/.test((err as Error).message))) {
    // add the policy.json positional argument
  }
}

Prevention

Remember policies validate takes a POSITIONAL path, not --file.
Use --json in scripts for structured {ok,error} output with exit 1 instead of a throw.
Run `hyperframes lambda policies user` first to see the canonical policy to validate against.

When it happens

Trigger: Running `hyperframes lambda policies validate` with no positional argument. Note the dispatcher threads args.extra as inputPath, so the path must be the third positional: `policies validate <policy.json>`.

Common situations: Forgetting the path; passing it as a flag (`--file x.json`) instead of a positional; a shell where the glob/path didn't expand.

Related errors

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