Can't create custom sidebar widgets from Devvit apps due to empty imageData array

Reproduce the moderator-scope addWidget calls from the issue, comparing textarea, custom with empty imageData, and custom with an uploaded image. Then inspect devvit/plugin/redditapi/widgets/widgets_msg.proto, especially WidgetImage, and the addWidget/updateWidget serialization paths. Done means no-image custom widgets can be created, or image metadata is mapped correctly, with the supported Devvit Web path documented.

Summary

Devvit apps with moderator scope can create textarea sidebar widgets, but reddit.addWidget({ type: 'custom' }) fails when we try to create a styled custom widget (HTML + CSS + height, no images).

reddit.updateWidget({ type: 'custom' }) can update text/css/height on an existing custom widget — but automated install/bootstrap cannot create the widget in the first place.

Environment

• Devvit Web app with moderator Reddit permissions
• @devvit/web / devvit: 0.13.7
• devvit.json: permissions.reddit.enable: true, scope: "moderator"
• Reproduced on a private playtest subreddit

What works (for comparison)

await reddit.addWidget({
  type: 'textarea',
  subreddit: context.subredditName!,
  shortName: 'My App Widget',
  text: '### Section title\n\nPlaceholder content',
  styles: { backgroundColor: '#0d0f11', headerColor: '#ffb900' },
});
// ✅ succeeds

What fails — example 1: CSS-only custom widget (no images)

This is what we need for a styled sidebar with scoped CSS and no widget images:

await reddit.addWidget({
  type: 'custom',
  subreddit: context.subredditName!,
  shortName: 'My App Widget',
  text: '# My App Widget\n\n*Placeholder*',
  css: '/**/',
  height: 200,
  imageData: [],
  styles: { backgroundColor: '#0d0f11', headerColor: '#ffb900' },
});

Observed errors (varies by attempt):

• Reddit rejects the payload when imageData is omitted or empty
• e.g. errors about imageData being missing or having an unexpected JSON structure when passing []

What fails — example 2: custom widget with lease-uploaded placeholder image

We also tried satisfying Reddit's imageData requirement with a 1×1 PNG via the widget image upload lease (S3 URL on an allowed domain):

await reddit.addWidget({
  type: 'custom',
  subreddit: context.subredditName!,
  shortName: 'My App Widget',
  text: '# My App Widget',
  css: '/**/',
  height: 200,
  imageData: [
    {
      url: 'https://reddit-subreddit-uploaded-media.s3-accelerate.amazonaws.com/...',
      linkUrl: '',
      width: 1,
      height: 1,
    },
  ],
  styles: { backgroundColor: '#0d0f11', headerColor: '#ffb900' },
});

Observed error:

JSON missing key: "name"

Reddit's API expects each imageData entry to include a name field. Devvit's WidgetImage proto only exposes url, linkUrl, width, height — no name — so the platform appears to strip or omit it before the request reaches Reddit.

Proto reference: devvit/plugin/redditapi/widgets/widgets_msg.proto → message WidgetImage

What partially works

If a custom widget already exists on the subreddit (created outside the app), Devvit can update it:

await reddit.updateWidget({
  type: 'custom',
  subreddit: context.subredditName!,
  id: existingWidgetId,
  shortName: 'My App Widget',
  text: '<p class="widget-title">...</p>',
  css: '/* scoped widget styles */',
  height: 280,
  imageData: [],
  styles: { backgroundColor: '#0d0f11', headerColor: '#ffb900' },
});
// ✅ appears to work when widget already exists (empty imageData omitted in UpdateCustomWidgetRequest.toJSON)

This is not viable for onAppInstall across all installing subreddits.

Expected

1. reddit.addWidget({ type: 'custom' }) should support no-image custom widgets (imageData: [])
2. If images are required, WidgetImage should include name (or map it correctly server-side)
3. Document the supported custom widget create path for Devvit Web

Impact

Apps that need styled sidebar content (HTML + CSS) cannot self-bootstrap on install. They fall back to plain textarea widgets or require manual setup outside Devvit.

Thanks!