fix(uploads): treat a missing storage object as absent metadata, not a failure

A workspace file is rewritten under a new key on every content update and the
superseded object is deleted, so any reader holding the previous key finds
nothing. getFileMetadata's provider lookups let that not-found propagate, so
authorization's catch-all logged it at ERROR and never reached the branch
already written for it. Return the function's established empty value instead,
and collapse the three divergent per-provider not-found predicates onto one.

Author: waleedlatif1

apps/sim/lib/uploads/core/errors.test.ts

@@ -0,0 +1,50 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { isObjectNotFoundError } from '@/lib/uploads/core/errors'
+
+describe('isObjectNotFoundError', () => {
+  it('matches the shapes each storage provider uses for a missing object', () => {
+    /** S3 HeadObject, exactly as the production payload arrived. */
+    expect(
+      isObjectNotFoundError({
+        name: 'NotFound',
+        $fault: 'client',
+        $metadata: { httpStatusCode: 404 },
+      })
+    ).toBe(true)
+    /** S3 GetObject. */
+    expect(isObjectNotFoundError({ name: 'NoSuchKey', $metadata: { httpStatusCode: 404 } })).toBe(
+      true
+    )
+    /** Azure Blob. */
+    expect(isObjectNotFoundError({ code: 'BlobNotFound', statusCode: 404 })).toBe(true)
+    /** GCS, which reports a numeric code. */
+    expect(isObjectNotFoundError({ code: 404 })).toBe(true)
+  })
+
+  it('matches on status alone when the provider sends no label', () => {
+    expect(isObjectNotFoundError({ $metadata: { httpStatusCode: 404 } })).toBe(true)
+    expect(isObjectNotFoundError({ statusCode: 404 })).toBe(true)
+  })
+
+  it('does not swallow a genuine failure', () => {
+    expect(
+      isObjectNotFoundError({ name: 'AccessDenied', $metadata: { httpStatusCode: 403 } })
+    ).toBe(false)
+    expect(
+      isObjectNotFoundError({ name: 'InternalError', $metadata: { httpStatusCode: 500 } })
+    ).toBe(false)
+    expect(isObjectNotFoundError({ name: 'TimeoutError' })).toBe(false)
+    expect(isObjectNotFoundError({ code: 'ECONNRESET' })).toBe(false)
+    expect(isObjectNotFoundError({ code: 403 })).toBe(false)
+  })
+
+  it('tolerates values that are not error objects', () => {
+    expect(isObjectNotFoundError(null)).toBe(false)
+    expect(isObjectNotFoundError(undefined)).toBe(false)
+    expect(isObjectNotFoundError('NotFound')).toBe(false)
+    expect(isObjectNotFoundError(404)).toBe(false)
+  })
+})

apps/sim/lib/uploads/core/errors.ts

@@ -0,0 +1,31 @@
+/**
+ * True when a storage provider reports that an object simply does not exist.
+ *
+ * Absence is an expected outcome of a lookup, not a failure, so callers turn this
+ * into an empty result rather than propagating it. Every provider spells it
+ * differently — S3 throws `NotFound` (HeadObject) or `NoSuchKey` (GetObject),
+ * Azure Blob throws `BlobNotFound`, and GCS throws a numeric `code: 404` — and the
+ * status may arrive as `$metadata.httpStatusCode`, `statusCode`, or `code`.
+ *
+ * Only genuine absence matches. A network failure, a permission denial, or a
+ * provider 5xx still propagates so it surfaces as the error it is.
+ */
+export function isObjectNotFoundError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false
+
+  const candidate = error as {
+    name?: unknown
+    code?: unknown
+    statusCode?: unknown
+    $metadata?: { httpStatusCode?: unknown }
+  }
+
+  const label = typeof candidate.name === 'string' ? candidate.name : candidate.code
+  if (label === 'NotFound' || label === 'NoSuchKey' || label === 'BlobNotFound') return true
+
+  return (
+    candidate.code === 404 ||
+    candidate.statusCode === 404 ||
+    candidate.$metadata?.httpStatusCode === 404
+  )
+}

apps/sim/lib/uploads/core/storage-client.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @vitest-environment node
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockGetFileMetadataByKey, mockSend, mockHeadObjectCommand } = vi.hoisted(() => ({
+  mockGetFileMetadataByKey: vi.fn(),
+  mockSend: vi.fn(),
+  mockHeadObjectCommand: vi.fn().mockImplementation(class {}),
+}))
+
+vi.mock('@aws-sdk/client-s3', () => ({
+  HeadObjectCommand: mockHeadObjectCommand,
+}))
+
+vi.mock('@/lib/uploads/config', () => ({
+  USE_S3_STORAGE: true,
+  USE_BLOB_STORAGE: false,
+  USE_GCS_STORAGE: false,
+  S3_CONFIG: { bucket: 'bucket', region: 'region' },
+}))
+
+vi.mock('@/lib/uploads/providers/s3/client', () => ({
+  getS3Client: () => ({ send: mockSend }),
+}))
+
+vi.mock('@/lib/uploads/server/metadata', () => ({
+  getFileMetadataByKey: mockGetFileMetadataByKey,
+}))
+
+import { getFileMetadata } from '@/lib/uploads/core/storage-client'
+
+/** The exact error the AWS SDK raises from HeadObject for an absent object. */
+const notFound = Object.assign(new Error('NotFound'), {
+  name: 'NotFound',
+  $fault: 'client',
+  $metadata: { httpStatusCode: 404 },
+})
+
+describe('getFileMetadata', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockGetFileMetadataByKey.mockResolvedValue(null)
+  })
+
+  it('reports an absent object as no metadata rather than throwing', async () => {
+    mockSend.mockRejectedValue(notFound)
+
+    await expect(getFileMetadata('workspace/ws/superseded-key.md')).resolves.toEqual({})
+  })
+
+  it('still propagates a genuine storage failure', async () => {
+    const denied = Object.assign(new Error('AccessDenied'), {
+      name: 'AccessDenied',
+      $metadata: { httpStatusCode: 403 },
+    })
+    mockSend.mockRejectedValue(denied)
+
+    await expect(getFileMetadata('workspace/ws/key.md')).rejects.toThrow('AccessDenied')
+  })
+
+  it('returns provider metadata when the object exists', async () => {
+    mockSend.mockResolvedValue({ Metadata: { workspaceid: 'ws-1' } })
+
+    await expect(getFileMetadata('workspace/ws/key.md')).resolves.toEqual({ workspaceid: 'ws-1' })
+  })
+
+  it('prefers the database record when one exists', async () => {
+    mockGetFileMetadataByKey.mockResolvedValue({
+      userId: 'user-1',
+      workspaceId: 'ws-1',
+      originalName: 'doc.md',
+      uploadedAt: new Date('2026-01-01T00:00:00Z'),
+      context: 'workspace',
+    })
+
+    const metadata = await getFileMetadata('workspace/ws/key.md')
+
+    expect(metadata.workspaceId).toBe('ws-1')
+    expect(mockSend).not.toHaveBeenCalled()
+  })
+})

apps/sim/lib/uploads/core/storage-client.ts

@@ -1,4 +1,5 @@
 import { USE_BLOB_STORAGE, USE_GCS_STORAGE, USE_S3_STORAGE } from '@/lib/uploads/config'
+import { isObjectNotFoundError } from '@/lib/uploads/core/errors'
 import type { StorageConfig } from '@/lib/uploads/shared/types'
 
 export type { StorageConfig } from '@/lib/uploads/shared/types'
@@ -29,6 +30,25 @@ export function getServePathPrefix(): string {
 export async function getFileMetadata(
   key: string,
   customConfig?: StorageConfig
+): Promise<Record<string, string>> {
+  try {
+    return await readProviderMetadata(key, customConfig)
+  } catch (error) {
+    /**
+     * A key that no longer resolves is an ordinary outcome — a workspace file is
+     * rewritten under a new key on every content update, so any reader holding the
+     * previous key finds nothing. Report it the way this function already reports
+     * "nothing known about this key" rather than as a failure, so callers fall
+     * through to their own not-found handling instead of an error path.
+     */
+    if (isObjectNotFoundError(error)) return {}
+    throw error
+  }
+}
+
+async function readProviderMetadata(
+  key: string,
+  customConfig?: StorageConfig
 ): Promise<Record<string, string>> {
   const { getFileMetadataByKey } = await import('../server/metadata')
   const metadataRecord = await getFileMetadataByKey(key)

apps/sim/lib/uploads/providers/blob/client.ts

@@ -20,6 +20,7 @@ import type {
 } from '@/lib/uploads/shared/types'
 import { sanitizeStorageMetadata } from '@/lib/uploads/utils/file-utils'
 import { sanitizeFileName } from '@/executor/constants'
+import { isObjectNotFoundError } from '@/lib/uploads/core/errors'
 
 const logger = createLogger('BlobClient')
 const MULTIPART_UPLOAD_ID_METADATA_KEY = 'sim_upload_id'
@@ -446,9 +447,7 @@ export async function headBlobObject(
       ...(properties.metadata ? { metadata: properties.metadata } : {}),
     }
   } catch (err) {
-    const status = (err as { statusCode?: number }).statusCode
-    const code = (err as { code?: string }).code
-    if (status === 404 || code === 'BlobNotFound') {
+    if (isObjectNotFoundError(err)) {
       return null
     }
     throw err
@@ -833,9 +832,7 @@ export async function abortMultipartUpload(
       await blockBlobClient.deleteIfExists()
     }
   } catch (error) {
-    const status = (error as { statusCode?: number }).statusCode
-    const code = (error as { code?: string }).code
-    if (status !== 404 && code !== 'BlobNotFound') {
+    if (!isObjectNotFoundError(error)) {
       logger.warn('Error cleaning up multipart upload:', error)
     }
   }

apps/sim/lib/uploads/providers/gcs/client.ts

@@ -24,6 +24,7 @@ import {
   sanitizeStorageMetadata,
 } from '@/lib/uploads/utils/file-utils'
 import { sanitizeFileName } from '@/executor/constants'
+import { isObjectNotFoundError } from '@/lib/uploads/core/errors'
 
 const logger = createLogger('GcsClient')
 
@@ -404,7 +405,7 @@ async function getGcsMultipartCompletionId(
     const metadata = await getGcsObjectMetadata(key, customConfig)
     return metadata[GCS_MULTIPART_UPLOAD_ID_METADATA_KEY] ?? null
   } catch (error) {
-    if ((error as { code?: number } | null)?.code === 404) return null
+    if (isObjectNotFoundError(error)) return null
     throw error
   }
 }

apps/sim/lib/uploads/providers/s3/client.ts

@@ -36,6 +36,7 @@ import {
   sanitizeStorageMetadata,
 } from '@/lib/uploads/utils/file-utils'
 import { sanitizeFileName } from '@/executor/constants'
+import { isObjectNotFoundError } from '@/lib/uploads/core/errors'
 
 let _s3Client: S3Client | null = null
 
@@ -260,10 +261,7 @@ export async function headS3Object(
       ...(response.Metadata ? { metadata: response.Metadata } : {}),
     }
   } catch (error) {
-    const code = (error as { name?: string; $metadata?: { httpStatusCode?: number } } | null)?.name
-    const status = (error as { $metadata?: { httpStatusCode?: number } } | null)?.$metadata
-      ?.httpStatusCode
-    if (code === 'NotFound' || code === 'NoSuchKey' || status === 404) {
+    if (isObjectNotFoundError(error)) {
       return null
     }
     throw error