musistudio/claude-code-router · error · Error

aspect_ratio is required for ${target.protocol}.

Error message

aspect_ratio is required for ${target.protocol}.

What it means

Thrown when the protocol marks aspect_ratio as a required parameter (constraints.requiredParameters includes "aspect_ratio") and no aspect_ratio argument was provided. Only some providers make this mandatory.

Source

Thrown at packages/core/src/media/service.ts:170

    const constraints = videoGenerationConstraints(target.protocol);
    const durationValue = numberValue(args.duration) ?? constraints.defaultDuration;
    if (durationValue === undefined) throw new Error(`duration is required for ${target.protocol}.`);
    if (!Number.isInteger(durationValue)) throw new Error("duration must be an integer number of seconds.");
    if (constraints.durations && !constraints.durations.includes(durationValue)) {
      throw new Error(`duration must be one of ${constraints.durations.join(", ")} seconds for ${target.protocol}.`);
    }
    if (constraints.durationMinimum !== undefined && constraints.durationMaximum !== undefined &&
      (durationValue < constraints.durationMinimum || durationValue > constraints.durationMaximum)) {
      throw new Error(`duration must be between ${constraints.durationMinimum} and ${constraints.durationMaximum} seconds for ${target.protocol}.`);
    }
    const resolution = optionalString(args.resolution) ?? constraints.defaultResolution;
    if (!resolution) throw new Error(`resolution is required for ${target.protocol}.`);
    if (!constraints.resolutions.includes(resolution)) {
      throw new Error(`resolution must be one of ${constraints.resolutions.join(", ")} for ${target.protocol}.`);
    }
    const aspectRatio = optionalString(args.aspect_ratio);
    if (constraints.requiredParameters.includes("aspect_ratio") && !aspectRatio) {
      throw new Error(`aspect_ratio is required for ${target.protocol}.`);
    }
    if (aspectRatio && !constraints.aspectRatios.includes(aspectRatio)) {
      throw new Error(`aspect_ratio must be one of ${constraints.aspectRatios.join(", ")} for ${target.protocol}.`);
    }
    const request: VideoGenerateRequest = {
      aspectRatio,
      duration: durationValue,
      images: args.images === undefined && args.image === undefined ? [] : this.validateImages(args.images ?? args.image, 1, 7),
      prompt: requiredPrompt(args.prompt),
      resolution
    };
    const job = this.submit("video-generate", request, modelPlan, optionalString(args.idempotency_key));
    return this.publicJob(job);
  }

  getJob(id: string): PublicMediaJob {
    const job = this.jobStore.get(id);
    if (!job) throw new Error(`Media job not found: ${id}`);

View on GitHub (pinned to 99f24806c6)

Solutions

1. Pass an allowed aspect ratio: videoStart({ aspect_ratio: "16:9", ... })
2. Check constraints.aspectRatios for the accepted values (listed in error 218's message)
3. Drive your UI's required-field state from constraints.requiredParameters

Example fix

// before
media.videoStart({ prompt, duration: 5, resolution: "720p" }, modelInput);

// after
media.videoStart({ prompt, duration: 5, resolution: "720p", aspect_ratio: "16:9" }, modelInput);

const c = videoGenerationConstraints(protocol);
if (c.requiredParameters.includes("aspect_ratio") && !args.aspect_ratio) {
  throw new Error("aspect_ratio required");
}

const requiresAspectRatio = (c: VideoConstraints): boolean =>
  c.requiredParameters.includes("aspect_ratio");

When it happens

Trigger: Starting video generation on a protocol that requires aspect_ratio without passing args.aspect_ratio.

Common situations: Switching to a provider that mandates aspect ratio where the previous one defaulted it (e.g. 16:9); minimal request payloads copied from another integration.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• aspect_ratio must be one of ${constraints.aspectRatios.join(
• duration is required for ${target.protocol}.
• duration must be an integer number of seconds.
• duration must be one of ${constraints.durations.join(", ")}
• duration must be between ${constraints.durationMinimum} and

AI-assisted analysis of musistudio/claude-code-router@99f24806c6 (2026-08-27). Data as JSON: /api/errors/08998a335775946c. Report an issue: GitHub.