fix(files): classify folder and content failures instead of 500ing them

Bugbot round 1. The v2 routes map errorCode straight to a status, so every
manager failure that arrived unclassified became a 500 for what is really a
caller-fixable 400 or 404.

- Folder manager throws OrchestrationError: missing target/folder -> not_found,
  reparent cycle / self-parent / restore-into-archived-workspace -> validation.
- File manager does the same for the in-transaction 'File not found' paths that
  the earlier pass missed.
- updateWorkspaceFileContent's outer catch re-wrapped everything in a bare
  Error, which stripped the class off StorageLimitExceededError and the new
  not_found alike. It now rethrows a classified failure untouched and attaches
  cause to the generic wrap, so asOrchestrationError can still walk the chain.
- Every remaining perform* gained the asOrchestrationError branch.
- renameWorkspaceFile returned the pre-update read, so the v2 PATCH reported a
  stale updatedAt; it now returns the timestamp it actually wrote.

Docs: upload auto-suffixes a duplicate name rather than rejecting it, matching
the in-app uploader. The description claimed 409 and was simply wrong.

Author: TheodoreSpeaks

apps/docs/openapi-v2-files-audit.json

@@ -144,7 +144,7 @@
       "post": {
         "operationId": "uploadFile",
         "summary": "Upload File",
-        "description": "Upload a file to a workspace as `multipart/form-data` with a single `file` field. The workspace — and the optional target `folderId` — are supplied as query parameters (not form fields) so authorization runs before the request body is buffered. Maximum file size is 100MB. A name already taken in the destination folder is rejected with `409`; the in-app uploader instead auto-suffixes, so the two surfaces differ here on purpose. Returns `201 Created`.\n\nPresigned upload is not part of the public API: it debits the storage quota only in a separate register step, so a caller that never registers would leave unaccounted bytes in storage. This buffered path debits inside the upload transaction.",
+        "description": "Upload a file to a workspace as `multipart/form-data` with a single `file` field. The workspace — and the optional target `folderId` — are supplied as query parameters (not form fields) so authorization runs before the request body is buffered. Maximum file size is 100MB. A name already taken in the destination folder is **not** an error: the name is auto-suffixed (`data.csv` -> `data (1).csv`), matching the in-app uploader, so a `201` can come back with a `name` different from the one you sent — always read `name` from the response rather than assuming it. `409` is returned only if a unique name cannot be allocated after several attempts. Use `PATCH /api/v2/files/{fileId}` if you need a specific name to be exact-or-fail. Returns `201 Created`.\n\nPresigned upload is not part of the public API: it debits the storage quota only in a separate register step, so a caller that never registers would leave unaccounted bytes in storage. This buffered path debits inside the upload transaction.",
         "tags": ["Files"],
         "x-codeSamples": [
           {
@@ -247,7 +247,7 @@
             "$ref": "#/components/responses/Forbidden"
           },
           "409": {
-            "description": "A file with the same name already exists in this workspace.",
+            "description": "A unique filename could not be allocated in the destination folder after several attempts. An ordinary name collision is auto-suffixed instead, not rejected.",
             "content": {
               "application/json": {
                 "schema": {
@@ -256,7 +256,7 @@
                 "example": {
                   "error": {
                     "code": "CONFLICT",
-                    "message": "A file with this name already exists in the workspace"
+                    "message": "A file named \"data.csv\" already exists in this workspace"
                   }
                 }
               }

apps/sim/lib/uploads/contexts/workspace/workspace-file-folder-manager.ts

@@ -4,6 +4,7 @@ import { createLogger } from '@sim/logger'
 import { getPostgresErrorCode } from '@sim/utils/errors'
 import { generateId } from '@sim/utils/id'
 import { and, asc, eq, inArray, isNull, min, type SQL, sql } from 'drizzle-orm'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { deduplicateFolderName } from '@/lib/folders/naming'
 import { collectDescendantFolderIds } from '@/lib/folders/subtree'
 import { getWorkspaceWithOwner } from '@/lib/workspaces/permissions/utils'
@@ -346,7 +347,7 @@ export async function assertWorkspaceFileFolderTarget(
 
   const folder = await getWorkspaceFileFolder(workspaceId, normalized)
   if (!folder) {
-    throw new Error('Target folder not found')
+    throw new OrchestrationError('not_found', 'Target folder not found')
   }
 
   return normalized
@@ -380,7 +381,7 @@ export async function createWorkspaceFileFolder(params: {
         .limit(1)
 
       if (!target) {
-        throw new Error('Target folder not found')
+        throw new OrchestrationError('not_found', 'Target folder not found')
       }
     }
 
@@ -558,7 +559,7 @@ export async function updateWorkspaceFileFolder(params: {
       )
       .limit(1)
 
-    if (!existing) throw new Error('Folder not found')
+    if (!existing) throw new OrchestrationError('not_found', 'Folder not found')
 
     const updates: Partial<typeof folderTable.$inferInsert> = { updatedAt: new Date() }
     const finalName =
@@ -568,7 +569,8 @@ export async function updateWorkspaceFileFolder(params: {
     const finalParentId =
       params.parentId !== undefined ? normalizeParentId(params.parentId) : existing.parentId
 
-    if (finalParentId === params.folderId) throw new Error('Folder cannot be its own parent')
+    if (finalParentId === params.folderId)
+      throw new OrchestrationError('validation', 'Folder cannot be its own parent')
 
     if (finalParentId) {
       const [target] = await tx
@@ -585,7 +587,7 @@ export async function updateWorkspaceFileFolder(params: {
         .limit(1)
 
       if (!target) {
-        throw new Error('Target folder not found')
+        throw new OrchestrationError('not_found', 'Target folder not found')
       }
     }
 
@@ -603,7 +605,10 @@ export async function updateWorkspaceFileFolder(params: {
 
       const descendants = collectDescendantFolderIds(activeFolders, params.folderId)
       if (finalParentId && descendants.includes(finalParentId)) {
-        throw new Error('Cannot move a folder into one of its descendants')
+        throw new OrchestrationError(
+          'validation',
+          'Cannot move a folder into one of its descendants'
+        )
       }
     }
 
@@ -653,7 +658,7 @@ export async function updateWorkspaceFileFolder(params: {
         )
         .returning()
 
-      if (!updatedFolder) throw new Error('Folder not found')
+      if (!updatedFolder) throw new OrchestrationError('not_found', 'Folder not found')
       return updatedFolder
     } catch (error) {
       if (getPostgresErrorCode(error) === '23505') {
@@ -717,12 +722,12 @@ export async function moveWorkspaceFileItems(params: {
         .limit(1)
 
       if (!target) {
-        throw new Error('Target folder not found')
+        throw new OrchestrationError('not_found', 'Target folder not found')
       }
     }
 
     if (folderIds.includes(targetFolderId ?? '')) {
-      throw new Error('Cannot move a folder into itself')
+      throw new OrchestrationError('validation', 'Cannot move a folder into itself')
     }
 
     if (folderIds.length > 0) {
@@ -740,7 +745,10 @@ export async function moveWorkspaceFileItems(params: {
       for (const folderId of folderIds) {
         const descendants = collectDescendantFolderIds(activeFolders, folderId)
         if (targetFolderId && descendants.includes(targetFolderId)) {
-          throw new Error('Cannot move a folder into one of its descendants')
+          throw new OrchestrationError(
+            'validation',
+            'Cannot move a folder into one of its descendants'
+          )
         }
       }
     }
@@ -891,7 +899,7 @@ export async function archiveWorkspaceFileFolderRecursive(
       )
       .limit(1)
 
-    if (!folder) throw new Error('Folder not found')
+    if (!folder) throw new OrchestrationError('not_found', 'Folder not found')
 
     const activeFolders = await tx
       .select({ id: folderTable.id, parentId: folderTable.parentId })
@@ -944,7 +952,7 @@ export async function restoreWorkspaceFileFolder(
 ): Promise<WorkspaceFileFolderRestoreResult> {
   const ws = await getWorkspaceWithOwner(workspaceId)
   if (!ws || ws.archivedAt) {
-    throw new Error('Cannot restore folder into an archived workspace')
+    throw new OrchestrationError('validation', 'Cannot restore folder into an archived workspace')
   }
 
   const { restored, restoredItems } = await db.transaction(async (tx) => {
@@ -959,8 +967,8 @@ export async function restoreWorkspaceFileFolder(
       .limit(1)
       .then((rows) => rows[0] ?? null)
 
-    if (!raw) throw new Error('Folder not found')
-    if (!raw.deletedAt) throw new Error('Folder is not archived')
+    if (!raw) throw new OrchestrationError('not_found', 'Folder not found')
+    if (!raw.deletedAt) throw new OrchestrationError('validation', 'Folder is not archived')
 
     const folderDeletedAt = raw.deletedAt
 

apps/sim/lib/uploads/contexts/workspace/workspace-file-manager.ts

@@ -19,7 +19,7 @@ import {
 } from '@/lib/billing/storage'
 import { normalizeVfsSegment } from '@/lib/copilot/vfs/normalize-segment'
 import { canonicalWorkspaceFilePath, decodeVfsPathSegments } from '@/lib/copilot/vfs/path-utils'
-import { OrchestrationError } from '@/lib/core/orchestration/types'
+import { asOrchestrationError, OrchestrationError } from '@/lib/core/orchestration/types'
 import { generateRequestId } from '@/lib/core/utils/request'
 import { generateRestoreName } from '@/lib/core/utils/restore-name'
 import type { DbOrTx } from '@/lib/db/types'
@@ -1123,7 +1123,7 @@ export async function updateWorkspaceFileContent(
           .for('update')
           .limit(1)
         if (!currentFile) {
-          throw new Error('File not found')
+          throw new OrchestrationError('not_found', 'File not found')
         }
 
         // Optimistic-concurrency guard: the row is `FOR UPDATE`-locked, so comparing its committed
@@ -1170,7 +1170,7 @@ export async function updateWorkspaceFileContent(
           )
           .returning()
         if (!updatedFile) {
-          throw new Error('File not found or could not be updated')
+          throw new OrchestrationError('not_found', 'File not found or could not be updated')
         }
 
         let updatedUsage: number | undefined
@@ -1256,8 +1256,15 @@ export async function updateWorkspaceFileContent(
     // the optimistic-concurrency guard, not a failure to wrap. The orphan upload was already cleaned up
     // by the inner finalization catch before it propagated here.
     if (error instanceof ContentVersionConflictError) throw error
+    // Same reasoning for an already-classified failure: a missing file and a blown storage quota are
+    // caller-fixable outcomes that every surface maps to 404/413 by class. Re-wrapping them in a bare
+    // Error stripped that classification and turned both into a 500.
+    const classified = asOrchestrationError(error)
+    if (classified) throw classified
     logger.error(`Failed to update workspace file content ${fileId}:`, error)
-    throw new Error(`Failed to update file content: ${getErrorMessage(error, 'Unknown error')}`)
+    throw new Error(`Failed to update file content: ${getErrorMessage(error, 'Unknown error')}`, {
+      cause: error,
+    })
   }
 }
 
@@ -1289,10 +1296,11 @@ export async function renameWorkspaceFile(
   }
 
   let updated: { id: string }[]
+  const renamedAt = new Date()
   try {
     updated = await db
       .update(workspaceFiles)
-      .set({ originalName: normalizedName, updatedAt: new Date() })
+      .set({ originalName: normalizedName, updatedAt: renamedAt })
       .where(
         and(
           eq(workspaceFiles.id, fileId),
@@ -1309,14 +1317,15 @@ export async function renameWorkspaceFile(
   }
 
   if (updated.length === 0) {
-    throw new Error('File not found or could not be renamed')
+    throw new OrchestrationError('not_found', 'File not found or could not be renamed')
   }
 
   logger.info(`Successfully renamed workspace file ${fileId} to "${normalizedName}"`)
 
   return {
     ...fileRecord,
     name: normalizedName,
+    updatedAt: renamedAt,
   }
 }
 
@@ -1337,7 +1346,7 @@ export async function moveRenameWorkspaceFile(params: {
 
   const fileRecord = await getWorkspaceFile(params.workspaceId, params.fileId)
   if (!fileRecord) {
-    throw new Error('File not found')
+    throw new OrchestrationError('not_found', 'File not found')
   }
 
   const targetFolderId = await assertWorkspaceFileFolderTarget(
@@ -1377,7 +1386,7 @@ export async function moveRenameWorkspaceFile(params: {
   }
 
   if (updated.length === 0) {
-    throw new Error('File not found or could not be moved')
+    throw new OrchestrationError('not_found', 'File not found or could not be moved')
   }
 
   return {
@@ -1400,7 +1409,7 @@ export async function deleteWorkspaceFile(workspaceId: string, fileId: string):
   try {
     const fileRecord = await findWorkspaceFileForLifecycle(db, workspaceId, fileId)
     if (!fileRecord) {
-      throw new Error('File not found')
+      throw new OrchestrationError('not_found', 'File not found')
     }
     if (fileRecord.deletedAt) return
 
@@ -1442,7 +1451,7 @@ export async function restoreWorkspaceFile(workspaceId: string, fileId: string):
 
   const ws = await getWorkspaceWithOwner(workspaceId)
   if (!ws || ws.archivedAt) {
-    throw new Error('Cannot restore file into an archived workspace')
+    throw new OrchestrationError('validation', 'Cannot restore file into an archived workspace')
   }
 
   /**