musistudio/claude-code-router · error

The CCR artifact content did not match its declared media ty

Error message

The CCR artifact content did not match its declared media type.

What it means

A CCR (Codex Chat Representation) media artifact was downloaded, but sniffing the byte content (magic-number detection) either failed to identify a known media type or produced a type whose kind (image/audio/video/etc.) differs from the kind declared in the artifact metadata. The library validates artifact integrity by comparing detectedMediaMimeType's kind against declaredKind and rejects mismatches to prevent rendering garbage or mis-typed payloads.

Source

Thrown at packages/core/src/agents/codex/media-preview-bridge.ts:337

  const chunks: Buffer[] = [];
  let total = 0;
  while (true) {
    const part = await reader.read();
    if (part.done) break;
    if (!part.value?.byteLength) continue;
    total += part.value.byteLength;
    if (total > maxBytes) {
      await reader.cancel();
      throw new Error("The CCR media artifact exceeds the inline preview size limit.");
    }
    chunks.push(Buffer.from(part.value));
  }
  if (!total) throw new Error("The CCR artifact response was empty.");
  if (declaredLength && total !== declaredLength) throw new Error("The CCR artifact response length did not match its headers.");
  const bytes = Buffer.concat(chunks, total);
  const detectedMimeType = detectMediaMimeType(bytes);
  if (!detectedMimeType || mediaKind(detectedMimeType) !== declaredKind) {
    throw new Error("The CCR artifact content did not match its declared media type.");
  }
  return { bytes, mimeType: detectedMimeType };
}

function detectMediaMimeType(buffer: Buffer): string | undefined {
  if (buffer.byteLength >= 8 && buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "image/png";
  if (buffer.byteLength >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) return "image/jpeg";
  if (buffer.byteLength >= 12 && buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP") return "image/webp";
  if (buffer.byteLength >= 12 && buffer.subarray(4, 8).toString("ascii") === "ftyp") {
    const brand = buffer.subarray(8, 12).toString("ascii");
    if (["avif", "avis", "mif1", "msf1"].includes(brand)) return "image/avif";
    return "video/mp4";
  }
  if (buffer.byteLength >= 4 && buffer.subarray(0, 4).equals(Buffer.from([0x1a, 0x45, 0xdf, 0xa3]))) return "video/webm";
  return undefined;
}

function mediaKind(mimeType: string): "image" | "video" | undefined {

View on GitHub (pinned to 99f24806c6)

Solutions

1. Verify the artifact bytes directly (download and run `file`/`xxd` on them) to see what the payload actually is
2. Check that the declared media type in the CCR artifact metadata matches the real file kind; fix the producer if mismatched
3. If the format is legitimate but unsupported, extend detectMediaMimeType with the appropriate magic bytes and upstream a patch
4. If an interceptor/proxy is rewriting responses, bypass it or fix it so raw artifact bytes flow through

Example fix

// before
const { bytes } = await loadCodexMediaArtifact(artifact);

// after
if (mediaKind(artifact.mimeType) !== 'image' && mediaKind(artifact.mimeType) !== 'audio') {
  throw new TypeError(`Unsupported declared kind: ${artifact.mimeType}`);
}
const { bytes } = await loadCodexMediaArtifact(artifact);

const kind = mediaKind(artifact.mimeType);
if (!kind) throw new TypeError(`Unknown declared media type: ${artifact.mimeType}`);
// optionally pre-fetch a HEAD/first bytes to sanity check

function isProbablyMediaKind(buf: Buffer, declared: string): boolean {
  const detected = detectMediaMimeType(buf);
  return !!detected && mediaKind(detected) === mediaKind(declared);
}

try { const m = await loadCodexMediaArtifact(a); } catch (e) { if (String(e).includes('did not match its declared media type')) { /* re-fetch artifact or flag upstream producer */ } throw e; }

When it happens

Trigger: Calling loadCodexMediaArtifact for a CCR artifact whose declared media kind (e.g. image) does not match the actual bytes (e.g. an HTML error page, truncated download, or a format detectMediaMimeType doesn't recognize); also triggered by corrupted/empty-ish buffers that pass the length check but fail magic-byte sniffing.

Common situations: Proxy or gateway returns an HTML/text error body with 200 status; artifact truncated by streaming bug; new/unsupported media format not in the magic-number table; wrong artifact ID mapping to different content.

Related errors

• The CCR artifact endpoint returned a non-media content type.
• The CCR media artifact exceeds the inline preview size limit
• Compressed CCR media artifacts are not accepted for inline p
• The CCR artifact response was empty.
• duration is required for ${target.protocol}.

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