nexu-io/open-design · error · Error

Vela model ${wireModel} does not publish a quality capabilit

Error message

Vela model ${wireModel} does not publish a quality capability, so quality ${tier} cannot be requested

What it means

Thrown by qualityArgs() when the caller requested a quality tier but the model's published capabilities have qualityValues === null — meaning the model publishes no quality capability at all. Only some models are tiered (the comment names gpt-image-2 as an example); asking an untiered model for a tier is rejected before the CLI call to avoid a guaranteed server-side failure.

Source

Thrown at apps/daemon/src/media/vela.ts:241

/**
 * Turn a requested tier into the `--quality` argument, or into nothing.
 *
 * Three outcomes, and the difference matters for billing: an unqualified
 * request sends no flag and is priced at the model's own default tier; a
 * request for a tier the model publishes sends it verbatim; a request the
 * model cannot honour fails here, before it costs anything, with the tiers it
 * does publish.
 */
function qualityArgs(
  requested: string | undefined,
  published: VelaPublishedImageCapabilities,
  wireModel: string,
): string[] {
  const tier = requested?.trim();
  if (!tier) return [];
  if (!published.qualityValues) {
    throw new Error(
      `Vela model ${wireModel} does not publish a quality capability, so quality ${tier} cannot be requested`,
    );
  }
  const publishedTier = matchPublishedValue(tier, published.qualityValues);
  if (!publishedTier) {
    throw new Error(
      `Vela model ${wireModel} does not publish quality ${tier}; supported: ${published.qualityValues.join(', ')}`,
    );
  }
  return ['--quality', publishedTier];
}

// Vela owns which shapes and tiers a model can actually deliver, so read the
// published capabilities per request instead of caching a copy here: a
// catalogue that gained or lost one must take effect immediately, and one
// extra CLI call is nothing beside the generation it precedes.
async function fetchPublishedImageCapabilities(
  input: VelaImageRenderInput,

View on GitHub (pinned to 5be4028344)

Solutions

Omit input.quality for models that do not publish tiers (let the server default apply)
Verify the model actually publishes a quality capability via `vela media models --json`
Pick a tiered model if a specific quality tier is required

Example fix

// before
await renderVelaImage({ ...input, model: 'vela/untiered-model', quality: 'high' });
// after
await renderVelaImage({ ...input, model: 'vela/untiered-model' }); // no quality

Defensive patterns

Strategy: validation

Validate before calling

function modelPublishesQuality(published: VelaPublishedImageCapabilities | null): boolean {
  return published?.qualityValues != null && published.qualityValues.length >= 0;
}

if (requestedQuality && !modelPublishesQuality(published)) {
  // drop quality and proceed with the server default
}

Type guard

function publishesQuality(p: { qualityValues: string[] | null }): p is { qualityValues: string[] } {
  return Array.isArray(p.qualityValues);
}

Try / catch

try {
  const args = qualityArgs(requestedQuality, published, wireModel);
} catch (err) {
  if (err instanceof Error && /does not publish a quality capability/.test(err.message)) {
    // retry without quality
  } else throw err;
}

Prevention

Only set input.quality for models known to publish a quality capability
Read `vela media models --json` once per session to learn which models are tiered
Default input.quality to undefined so untiered models use the server default

When it happens

Trigger: Calling renderVelaImage with input.quality set, where the model was found in the catalogue (published is non-null) but its capabilities.quality object is absent, so qualityValues resolved to null.

Common situations: Caller assumed a model supports quality tiers when it does not; model was downgraded/changed and lost its tier capability; quality was hardcoded for a tiered model but applied to an untiered one.

Related errors

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/0c4b58f688730a45. Report an issue: GitHub.