fix(cli): refuse delta uploads over 10k files + docs (#2759)

riderx · cursoragent · web-flow · commit 87cbc994b7b7 · 2026-07-27T13:26:55.000+02:00
* fix(cli): refuse delta uploads over 10k files

Match the set_manifest entry cap in the CLI before creating a version or
uploading files, document the limit, and cover the backend rejection.

Co-authored-by: Martin DONADIEU &lt;martindonadieu@gmail.com&gt;

* chore: retrigger CI after concurrency cancel

Co-authored-by: Martin DONADIEU &lt;martindonadieu@gmail.com&gt;

* chore: retrigger CI for clean Run tests pass

Co-authored-by: Martin DONADIEU &lt;martindonadieu@gmail.com&gt;

* fix(cli): explain delta 10k file limit to users

Give a clear why/what-to-do message when refusing oversized delta
uploads, and align API/docs wording with the same guidance.

Co-authored-by: Martin DONADIEU &lt;martindonadieu@gmail.com&gt;

* fix(api): clarify set_manifest too-large error message

Co-authored-by: Martin DONADIEU &lt;martindonadieu@gmail.com&gt;

---------

Co-authored-by: Cursor Agent &lt;cursoragent@cursor.com&gt;
diff --git a/cli/skills/release-management/SKILL.md b/cli/skills/release-management/SKILL.md
@@ -71,7 +71,7 @@ Use this skill for OTA update workflows in Capgo Cloud.
   - `--zip`
   - `--tus`
   - `--tus-chunk-size <tusChunkSize>`
-  - `--delta`
+  - `--delta` (refuses over 10,000 files — delta tracks each file; use `--no-delta` for a full zip, or reduce build files)
   - `--delta-only`
   - `--no-delta`
   - `--encrypted-checksum <encryptedChecksum>`
diff --git a/cli/src/bundle/partial.ts b/cli/src/bundle/partial.ts
@@ -14,7 +14,7 @@ import { parse } from '@std/semver'
 import * as micromatch from 'micromatch'
 import * as tus from 'tus-js-client'
 import { encryptChecksum, encryptChecksumV3, encryptSource } from '../api/crypto'
-import { BROTLI_MIN_UPDATER_VERSION_V5, BROTLI_MIN_UPDATER_VERSION_V6, BROTLI_MIN_UPDATER_VERSION_V7, findRoot, generateManifest, getContentType, getInstalledVersion, getLocalConfig, isDeprecatedPluginVersion, sendEvent, TUS_UPLOAD_RETRY_DELAYS } from '../utils'
+import { BROTLI_MIN_UPDATER_VERSION_V5, BROTLI_MIN_UPDATER_VERSION_V6, BROTLI_MIN_UPDATER_VERSION_V7, deltaManifestTooLargeMessage, findRoot, generateManifest, getContentType, getInstalledVersion, getLocalConfig, isDeprecatedPluginVersion, MAX_MANIFEST_ENTRIES, sendEvent, TUS_UPLOAD_RETRY_DELAYS } from '../utils'
 
 // Check if file already exists on server (bypass cache and force storage lookup)
 async function fileExists(localConfig: any, filename: string): Promise<boolean> {
@@ -231,6 +231,10 @@ export async function uploadPartial(
     throw new Error(`Files with spaces in their names (${filesWithSpaces.map(f => f.file).join(', ')}). Please rename the files.`)
   }
 
+  if (manifest.length > MAX_MANIFEST_ENTRIES)
+    throw new Error(deltaManifestTooLargeMessage(manifest.length))
+
+
   let uploadedFiles = 0
   const totalFiles = manifest.length
   let brFilesCount = 0
diff --git a/cli/src/bundle/upload.ts b/cli/src/bundle/upload.ts
@@ -23,7 +23,7 @@ import { confirmWithRememberedChoice } from '../promptPreferences'
 import { showReplicationProgress } from '../replicationProgress'
 import { formatTable } from '../terminal-table'
 import { usesAlwaysDirectUpdate } from '../updaterConfig'
-import { baseKeyV2, BROTLI_MIN_UPDATER_VERSION_V5, BROTLI_MIN_UPDATER_VERSION_V6, BROTLI_MIN_UPDATER_VERSION_V7, canPromptInteractively, checkCompatibilityCloud, checkPlanValidUpload, checkRemoteCliMessages, createSupabaseClient, deletedFailedVersion, findRoot, findSavedKey, formatError, getAppId, getBundleVersion, getCompatibilityDetails, getConfig, getInstalledVersion, getLocalConfig, getLocalDependencies, getOrganizationId, getPMAndCommand, getRemoteChecksums, getRemoteFileConfig, hasCliPermission, isCompatible, isDeprecatedPluginVersion, regexSemver, resolveUserIdFromApiKey, sendEvent, setVersionManifest, updateConfigUpdater, updateOrCreateChannel, updateOrCreateVersion, UPLOAD_TIMEOUT, uploadTUS, uploadUrl, zipFile } from '../utils'
+import { baseKeyV2, BROTLI_MIN_UPDATER_VERSION_V5, BROTLI_MIN_UPDATER_VERSION_V6, BROTLI_MIN_UPDATER_VERSION_V7, canPromptInteractively, checkCompatibilityCloud, checkPlanValidUpload, checkRemoteCliMessages, createSupabaseClient, deletedFailedVersion, deltaManifestTooLargeMessage, findRoot, findSavedKey, formatError, getAppId, getBundleVersion, getCompatibilityDetails, getConfig, getInstalledVersion, getLocalConfig, getLocalDependencies, getOrganizationId, getPMAndCommand, getRemoteChecksums, getRemoteFileConfig, hasCliPermission, isCompatible, isDeprecatedPluginVersion, MAX_MANIFEST_ENTRIES, regexSemver, resolveUserIdFromApiKey, sendEvent, setVersionManifest, updateConfigUpdater, updateOrCreateChannel, updateOrCreateVersion, UPLOAD_TIMEOUT, uploadTUS, uploadUrl, zipFile } from '../utils'
 import { getVersionSuggestions, interactiveVersionBump } from '../versionHelpers'
 import { maybePromptBuilderCta, shouldBlockIncompatibleUpload } from './builder-cta'
 import { checkIndexPosition, searchInDirectory } from './check'
@@ -1510,6 +1510,11 @@ export async function uploadBundleInternal(preAppid: string, options: OptionsUpl
   if (options.verbose && options.delta)
     log.info(`[Verbose] Delta manifest prepared with ${manifest.length} files`)
 
+  // Refuse before creating a version row or uploading files (matches set_manifest cap).
+  if (options.delta && manifest.length > MAX_MANIFEST_ENTRIES)
+    uploadFail(deltaManifestTooLargeMessage(manifest.length))
+
+
   if (options.verbose)
     log.info(`[Verbose] Creating version record in database...`)
 
diff --git a/cli/src/index.ts b/cli/src/index.ts
@@ -260,7 +260,7 @@ Example: npx @capgo/cli@latest bundle upload com.example.app --path ./dist --cha
   .option('--tus-chunk-size <tusChunkSize>', `Chunk size in bytes for TUS resumable uploads (default: auto)`)
   .option('--partial', `[DEPRECATED] Use --delta instead. Upload incremental updates`)
   .option('--partial-only', `[DEPRECATED] Use --delta-only instead. Upload only incremental updates, skip full bundle`)
-  .option('--delta', `Upload delta updates (only changed files) for instant, super-fast updates instead of big zip downloads`)
+  .option('--delta', `Upload delta updates (only changed files) for instant, super-fast updates instead of big zip downloads. Capgo refuses delta uploads over 10,000 files (delta tracks each file); use --no-delta for a full zip, or reduce files in your web build.`)
   .option('--delta-only', `Upload only delta updates without full bundle for maximum speed (useful for large apps)`)
   .option('--no-delta', `Disable delta updates even if instant updates are enabled`)
   .option('--encrypted-checksum <encryptedChecksum>', `An encrypted checksum (signature). Used only when uploading an external bundle.`)
diff --git a/cli/src/utils.ts b/cli/src/utils.ts
@@ -52,6 +52,22 @@ export const ALERT_UPLOAD_SIZE_BYTES = 1024 * 1024 * 20 // 20MB
 export const MAX_UPLOAD_LENGTH_BYTES = 1024 * 1024 * 1024 // 1GB
 export const MAX_CHUNK_SIZE_BYTES = 1024 * 1024 * 99 // 99MB
 export const TUS_UPLOAD_RETRY_DELAYS = [0, 1000, 3000, 5000, 10000]
+// Keep in sync with supabase/functions/_backend/private/set_manifest.ts
+export const MAX_MANIFEST_ENTRIES = 10_000
+
+/** User-facing error when a delta/manifest upload exceeds MAX_MANIFEST_ENTRIES. */
+export function deltaManifestTooLargeMessage(fileCount: number): string {
+  const max = MAX_MANIFEST_ENTRIES.toLocaleString('en-US')
+  const count = fileCount.toLocaleString('en-US')
+  return [
+    `Delta updates cannot upload this bundle: it has ${count} files, and Capgo allows at most ${max} files per delta (manifest) upload.`,
+    'Delta mode tracks and uploads each file individually so devices can download only what changed. Very large file counts are not supported on that path.',
+    'What you can do:',
+    `1. Upload a full zip instead: npx @capgo/cli@latest bundle upload --no-delta`,
+    '2. Or reduce files in your web build output (remove unused assets, avoid copying large trees into dist).',
+    'See https://capgo.app/docs/faq/#are-there-delta-update-file-path-limitations',
+  ].join('\n')
+}
 
 export const PACKNAME = 'package.json'
 
diff --git a/cli/webdocs/bundle.mdx b/cli/webdocs/bundle.mdx
@@ -69,7 +69,7 @@ npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel prod
 | **--tus-chunk-size** | <code>string</code> | Chunk size in bytes for TUS resumable uploads (default: auto) |
 | **--partial** | <code>boolean</code> | [DEPRECATED] Use --delta instead. Upload incremental updates |
 | **--partial-only** | <code>boolean</code> | [DEPRECATED] Use --delta-only instead. Upload only incremental updates, skip full bundle |
-| **--delta** | <code>boolean</code> | Upload delta updates (only changed files) for instant, super-fast updates instead of big zip downloads |
+| **--delta** | <code>boolean</code> | Upload delta updates (only changed files) for instant, super-fast updates instead of big zip downloads. Capgo refuses delta uploads over 10,000 files because delta mode tracks each file individually; use --no-delta for a full zip, or reduce files in your web build. |
 | **--delta-only** | <code>boolean</code> | Upload only delta updates without full bundle for maximum speed (useful for large apps) |
 | **--no-delta** | <code>boolean</code> | Disable delta updates even if instant updates are enabled |
 | **--encrypted-checksum** | <code>string</code> | An encrypted checksum (signature). Used only when uploading an external bundle. |
diff --git a/supabase/functions/_backend/private/set_manifest.ts b/supabase/functions/_backend/private/set_manifest.ts
@@ -43,7 +43,7 @@ app.post('/', middlewareKey(), async (c) => {
   if (!Array.isArray(body.manifest) || body.manifest.length === 0)
     return quickError(400, 'error_manifest_missing', 'Error manifest missing or empty', { body })
   if (body.manifest.length > MAX_MANIFEST_ENTRIES) {
-    return quickError(400, 'error_manifest_too_large', 'Manifest has too many entries', {
+    return quickError(400, 'error_manifest_too_large', `Delta manifests are limited to ${MAX_MANIFEST_ENTRIES} files (got ${body.manifest.length}). Use a full zip upload (--no-delta) or reduce files in the web build.`, {
       max: MAX_MANIFEST_ENTRIES,
       count: body.manifest.length,
     })
diff --git a/tests/set-manifest.test.ts b/tests/set-manifest.test.ts
@@ -212,6 +212,48 @@ describe('[POST] /private/set_manifest', () => {
     expect(json.error).toBe('error_version_already_finalized')
   })
 
+  it('rejects manifests larger than 10,000 entries', async () => {
+    const oversizedName = `${BUNDLE_NAME}-too-large`
+    const { data: version, error } = await getSupabaseClient()
+      .from('app_versions')
+      .insert({
+        app_id: APP_ID,
+        name: oversizedName,
+        checksum: randomUUID().replaceAll('-', ''),
+        owner_org: ORG_ID,
+        user_id: USER_ID,
+        storage_provider: 'r2-direct',
+        deleted: false,
+      })
+      .select('owner_org')
+      .single()
+    expect(error).toBeNull()
+
+    const prefix = `orgs/${version!.owner_org}/apps/${APP_ID}/delta`
+    const oversized = Array.from({ length: 10_001 }, (_, i) => ({
+      file_name: `f${i}.js`,
+      s3_path: `${prefix}/h${i}_f${i}.js`,
+      file_hash: `h${i}`,
+    }))
+
+    const response = await fetchTestRequest(getEndpointUrl('/private/set_manifest'), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': APIKEY_TEST_ALL,
+      },
+      body: JSON.stringify({
+        app_id: APP_ID,
+        name: oversizedName,
+        manifest: oversized,
+      }),
+    })
+
+    expect(response.status).toBe(400)
+    const json = await response.json() as { error: string, max?: number, count?: number }
+    expect(json.error).toBe('error_manifest_too_large')
+  })
+
   it('rejects missing versions and non-uploadable storage providers', async () => {
     const missing = await fetchTestRequest(getEndpointUrl('/private/set_manifest'), {
       method: 'POST',
