mastra-ai/mastra · error · HTTPException

metadata.avatarUrl is empty

Error message

metadata.avatarUrl is empty

What it means

HTTP 400 from validateMetadataAvatarUrl: although the base64 string passed strict format checks, decoding it yields zero bytes — an effectively empty avatar. Rejected so agents never store a no-op image.

Source

Thrown at packages/server/src/server/handlers/validate-avatar.ts:39

      message: 'metadata.avatarUrl must be a valid data URL (data:<mime>;base64,<data>)',
    });
  }

  // `Buffer.from(..., 'base64')` decodes leniently — it silently ignores
  // invalid characters and never throws. Validate the payload format strictly
  // before measuring its byte length so malformed input is rejected.
  const base64Payload = match[2]!;
  const isStrictBase64 =
    base64Payload.length > 0 &&
    base64Payload.length % 4 === 0 &&
    /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(base64Payload);
  if (!isStrictBase64) {
    throw new HTTPException(400, { message: 'metadata.avatarUrl contains invalid base64' });
  }
  const byteLength = Buffer.from(base64Payload, 'base64').byteLength;

  if (byteLength === 0) {
    throw new HTTPException(400, { message: 'metadata.avatarUrl is empty' });
  }

  if (byteLength > AVATAR_MAX_BYTES) {
    throw new HTTPException(413, {
      message: `metadata.avatarUrl exceeds ${AVATAR_MAX_BYTES}-byte limit (got ${byteLength})`,
    });
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Remove the avatarUrl key (or set it to null) to clear an avatar instead of sending an empty data URL.
2. Verify the source file/buffer is non-empty before base64-encoding and submitting.

Example fix

// before
metadata: { avatarUrl: 'data:image/png;base64,' }
// after
metadata: {} // omit avatarUrl to clear it

const payload = metadata?.avatarUrl?.split(',')[1] ?? '';
if (typeof metadata?.avatarUrl === 'string' && Buffer.from(payload, 'base64').byteLength === 0) {
  delete metadata.avatarUrl; // treat as 'no avatar'
}

When it happens

Trigger: avatarUrl like 'data:image/png;base64,' with an empty payload that still passed earlier checks, or a payload that decodes to zero bytes.

Common situations: Clearing an avatar by sending an empty data URL instead of omitting/nulling the key; image processing pipelines that emit empty buffers on failure.

Related errors

• metadata.avatarUrl must be a string
• bad request: ${responseText}
• Rule metadata is too large.
• MASTRA_ADD_WORKSPACE_MISSING_AGENT_METADATA
• Invalid metadata key: "${key}".

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/2f6f40c531de78a3. Report an issue: GitHub.