@@ -0,0 +1,18 @@
+---
+'@object-ui/fields': patch
+---
+
+fix(fields): a failed image upload is reported in `ImageField`, not swallowed
+
+Both upload paths of `ImageField` — the native picker and the crop dialog's
+confirm — ran the upload inside `try … finally` with no `catch`. Both are
+invoked fire-and-forget (React ignores the promise an `onChange` handler returns,
+and the cropper does not await `onConfirm`), so a rejected upload (a network
+error, a 413, a storage outage) showed the user nothing and escaped as an
+unhandled promise rejection.
+
+A failed upload now renders the same translated `fields.file.uploadFailed`
+message `FileField` shows for the same failure, in the widget's existing error
+row. The failed image is not added: on the picker path the other picks of a
+multi-select still upload and land, as in `FileField`; on the crop path the
+original image stays and the dialog closes so the message is visible.
@@ -23,6 +23,22 @@ const ImageCropperDialog = lazy(() =>
   import('./ImageCropperDialog.js').then((m) => ({ default: m.ImageCropperDialog })),
 );
 
+/**
+ * The message for a failed upload — the same translated key, arguments and
+ * fallback FileField renders for the same failure through the same
+ * `useUpload()` transport (objectui#10226). Both upload paths in `ImageField`
+ * are invoked fire-and-forget (React ignores the promise an `onChange` handler
+ * returns; the cropper does not await `onConfirm`), so a failure not caught
+ * there is reported nowhere — it escapes as an unhandled rejection.
+ */
+function uploadFailedMessage(t: TranslateFn, name: string, err: unknown): string {
+  return t('fields.file.uploadFailed', {
+    defaultValue: `Failed to upload "${name}": ${(err as Error).message}`,
+    name,
+    error: (err as Error).message,
+  });
+}
+
 /**
  * ImageField - Image upload widget with preview thumbnails
  * Supports single and multiple image uploads with drag-and-drop and preview display
@@ -47,7 +63,10 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
   const { upload } = useUpload();
   const { t } = useObjectTranslation();
   const [uploading, setUploading] = useState(false);
-  /** Client-side rejections (oversize picks), cleared on the next attempt. */
+  /**
+   * Per-pick failures shown under the button, cleared on the next attempt:
+   * client-side rejections (oversize picks) and failed uploads.
+   */
   const [errors, setErrors] = useState<string[]>([]);
   // Display details of just-uploaded images, keyed by their new `sys_file` id.
   // Submitting the reference form means the field value no longer carries the
@@ -97,6 +116,10 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
         } else {
           onChange(next);
         }
+      } catch (err) {
+        // The original image stays in place; the dialog closes in `finally`,
+        // so the message lands in the field's error row, not behind it.
+        setErrors([uploadFailedMessage(t as TranslateFn, name, err)]);
       } finally {
         releaseScope();
         setUploading(false);
@@ -176,19 +199,30 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
     });
     setErrors(rejections);
     if (validFiles.length === 0) return;
+    const failures: string[] = [];
 
     // Released only after `onChange` has handed the value over, and whether or
     // not this widget is still mounted by then — see FileField's pipeline.
     const releaseScope = holdScope();
     setUploading(true);
     try {
-      const imageObjects = await Promise.all(
+      // Each pick is caught on its own, as FileField does: a failed pick is
+      // reported and not added, and the picks that did upload still land.
+      const uploaded = await Promise.all(
         validFiles.map(async (file) => {
-          const result = await upload(file);
-          remember(result, file.name);
-          return fileValueForSubmit(result, file.name);
+          try {
+            const result = await upload(file);
+            remember(result, file.name);
+            return fileValueForSubmit(result, file.name);
+          } catch (err) {
+            failures.push(uploadFailedMessage(t as TranslateFn, file.name, err));
+            return null;
+          }
         }),
       );
+      if (failures.length > 0) setErrors([...rejections, ...failures]);
+      const imageObjects = uploaded.filter((v) => v !== null);
+      if (imageObjects.length === 0) return;
 
       if (multiple) {
         onChange([...images, ...imageObjects]);
@@ -287,9 +321,8 @@ export function ImageField({ value, onChange, field, readonly, onUploadingChange
               : t('fields.image.upload')}
         </Button>
 
-        {/* Client-side rejections (oversize picks). Same presentation as
-            FileField's error row — this widget previously had no surface for
-            them at all, because it never rejected anything (objectui#4141). */}
+        {/* Oversize picks (objectui#4141) and failed uploads (objectui#10226).
+            Same presentation as FileField's error row. */}
         {errors.length > 0 && (
           <div className="space-y-0.5">
             {errors.map((err, i) => (
 
@@ -0,0 +1,169 @@
+/**
+ * ImageField — a FAILED upload is reported inline, the image is not added,
+ * and the rejection never escapes the handler (objectui#10226).
+ *
+ * The defect this pins: both upload paths (`handleFileChange` for the native
+ * picker, `handleCropConfirm` for the crop dialog) were `try … finally` with no
+ * `catch`. Both are invoked fire-and-forget — React ignores the promise an
+ * `onChange` handler returns, and the cropper calls `onConfirm` without
+ * awaiting it — so a rejecting upload surfaced as an unhandled promise
+ * rejection and the user saw nothing at all. FileField, on the same failure
+ * through the same `useUpload()` transport, renders `fields.file.uploadFailed`.
+ *
+ * So each failure case asserts three facts together: the translated failure
+ * text is in the DOM, `onChange` was not called with the failed image, and the
+ * process saw zero `unhandledRejection` events. The success cases are the
+ * control — the same harness with a resolving transport still adds the image.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { UploadProvider, type UploadAdapter } from '@object-ui/providers';
+import { ImageField } from './ImageField';
+// Imported at module scope (not awaited in a hook) so the widget's
+// `React.lazy(() => import('./ImageCropperDialog'))` resolves from the ESM
+// cache instead of racing RTL's 1000ms `findBy` budget — AGENTS.md §测试纪律.
+import './ImageCropperDialog';
+
+function image(name: string): File {
+  return new File(['x'], name, { type: 'image/png' });
+}
+
+/**
+ * `upload` rejects for any name listed in `failing`, resolves otherwise. A crop
+ * uploads a bare `Blob`, which carries no name, so it is keyed `cropped.png`.
+ */
+function renderField(field: Record<string, unknown>, value: unknown, failing: string[]) {
+  const upload = vi.fn(async (f: File | Blob) => {
+    const name = (f as File).name ?? 'cropped.png';
+    if (failing.includes(name)) throw new Error('network down');
+    return { url: `https://cdn.example/${name}`, name, size: f.size, mimeType: 'image/png' };
+  });
+  const adapter: UploadAdapter = { name: 'spy', upload };
+  const onChange = vi.fn();
+  render(
+    <UploadProvider adapter={adapter}>
+      <ImageField field={field as any} value={value} onChange={onChange} />
+    </UploadProvider>,
+  );
+  return { upload, onChange, input: document.querySelector('input[type="file"]') as HTMLInputElement };
+}
+
+/**
+ * Node's `process`, reached through `globalThis` with only the two members this
+ * file uses typed — this package's test program deliberately carries no
+ * `@types/node` (see `tsconfig.test.json`).
+ */
+type RejectionListener = (reason: unknown) => void;
+const nodeProcess = (globalThis as unknown as {
+  process: {
+    on(event: 'unhandledRejection', listener: RejectionListener): void;
+    off(event: 'unhandledRejection', listener: RejectionListener): void;
+  };
+}).process;
+
+/** Lets the event loop turn so a pending `unhandledRejection` is dispatched. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 20));
+
+const existing = { name: 'cover.png', url: 'https://cdn.example/cover.png', mime_type: 'image/png' };
+
+describe('ImageField — a failed upload is reported, not swallowed (#10226)', () => {
+  let unhandled: unknown[];
+  const onUnhandled = (reason: unknown) => {
+    unhandled.push(reason);
+  };
+  beforeEach(() => {
+    unhandled = [];
+    nodeProcess.on('unhandledRejection', onUnhandled);
+  });
+  afterEach(() => {
+    nodeProcess.off('unhandledRejection', onUnhandled);
+  });
+
+  it('picker: shows the translated failure, adds nothing, leaks no rejection', async () => {
+    const { upload, onChange, input } = renderField({ name: 'p_cover' }, undefined, ['bad.png']);
+
+    fireEvent.change(input, { target: { files: [image('bad.png')] } });
+
+    await waitFor(() => expect(upload).toHaveBeenCalledTimes(1));
+    await settle();
+    expect.soft(unhandled).toHaveLength(0);
+    expect.soft(onChange).not.toHaveBeenCalled();
+    await screen.findByText('Failed to upload "bad.png": network down');
+    // The button leaves its uploading state, so the user can retry.
+    expect(screen.getByTestId('image-field-upload-button').hasAttribute('disabled')).toBe(false);
+  });
+
+  it('picker (multiple): adds the successful picks and reports only the failed one', async () => {
+    const { upload, onChange, input } = renderField({ name: 'p_gallery', multiple: true }, undefined, ['bad.png']);
+
+    fireEvent.change(input, { target: { files: [image('good.png'), image('bad.png')] } });
+
+    await waitFor(() => expect(upload).toHaveBeenCalledTimes(2));
+    await settle();
+    expect.soft(unhandled).toHaveLength(0);
+    await screen.findByText('Failed to upload "bad.png": network down');
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    const added = onChange.mock.calls[0][0] as unknown[];
+    expect(added).toHaveLength(1);
+    expect(JSON.stringify(added)).toContain('https://cdn.example/good.png');
+    expect(JSON.stringify(added)).not.toContain('bad.png');
+  });
+
+  it('picker control: a resolving upload is still added', async () => {
+    const { onChange, input } = renderField({ name: 'p_cover' }, undefined, []);
+
+    fireEvent.change(input, { target: { files: [image('good.png')] } });
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    await settle();
+    expect(JSON.stringify(onChange.mock.calls[0][0])).toContain('https://cdn.example/good.png');
+    expect(screen.queryByText(/Failed to upload/)).toBeNull();
+    expect(unhandled).toHaveLength(0);
+  });
+
+  it('crop: shows the translated failure, keeps the original image, leaks no rejection', async () => {
+    const { upload, onChange } = renderField({ name: 'p_cover', crop: true }, existing, ['cropped.png']);
+
+    fireEvent.click(screen.getByTestId('image-field-crop-0'));
+    fireEvent.click(await screen.findByTestId('fake-crop-confirm'));
+
+    await waitFor(() => expect(upload).toHaveBeenCalledTimes(1));
+    await settle();
+    expect.soft(unhandled).toHaveLength(0);
+    expect.soft(onChange).not.toHaveBeenCalled();
+    await screen.findByText('Failed to upload "cover.png": network down');
+    // The dialog closes so the message is not hidden behind it.
+    expect(screen.queryByTestId('fake-crop-confirm')).toBeNull();
+  });
+
+  it('crop control: a resolving upload still replaces the image', async () => {
+    const { onChange } = renderField({ name: 'p_cover', crop: true }, existing, []);
+
+    fireEvent.click(screen.getByTestId('image-field-crop-0'));
+    fireEvent.click(await screen.findByTestId('fake-crop-confirm'));
+
+    await waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    await settle();
+    expect(JSON.stringify(onChange.mock.calls[0][0])).toContain('https://cdn.example/cropped.png');
+    expect(screen.queryByText(/Failed to upload/)).toBeNull();
+    expect(unhandled).toHaveLength(0);
+  });
+});
+
+/**
+ * The real cropper is a canvas + `toBlob` pipeline that happy-dom cannot run;
+ * this stand-in drives the one contract ImageField has with it — `onConfirm`
+ * hands back a blob and a name, fire-and-forget, exactly as the real dialog
+ * calls it (it does not await the returned promise).
+ */
+vi.mock('./ImageCropperDialog', () => ({
+  ImageCropperDialog: ({ onConfirm }: { onConfirm: (blob: Blob, name: string) => void }) => (
+    <button
+      type="button"
+      data-testid="fake-crop-confirm"
+      onClick={() => onConfirm(new Blob(['x'], { type: 'image/png' }), 'cover.png')}
+    >
+      confirm
+    </button>
+  ),
+}));