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

[brperry]

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!