What causes "File not found in storage: ${stub.name}" in Stirling-Tools/Stirling-PDF?

Filter missing files out and proceed with the available subset, warning the user which files were dropped, rather than failing the whole selection.

Stirling-Tools/Stirling-PDF · error · Error

File not found in storage: ${stub.name}

Error message

File not found in storage: ${stub.name}

What it means

Thrown inside `selectMultipleFiles` when `fileStorage.getStirlingFile(stub.id)` returns null for a selected stub. The stub is in UI state and selected, but its full StirlingFile blob is no longer in storage — so it cannot be handed to the consumer's onStirlingFilesSelect callback.

Source

Thrown at frontend/editor/src/core/hooks/useFileManager.ts:478

      };

      const selectMultipleFiles = async (
        files: StirlingFileStub[],
        onStirlingFilesSelect: (stirlingFiles: StirlingFile[]) => void,
      ) => {
        if (selectedFiles.length === 0) return;

        try {
          // Filter by UUID and load full StirlingFile objects directly
          const selectedFileObjects = files.filter((f) =>
            selectedFiles.includes(f.id),
          );

          const stirlingFiles = await Promise.all(
            selectedFileObjects.map(async (stub) => {
              const stirlingFile = await fileStorage.getStirlingFile(stub.id);
              if (!stirlingFile) {
                throw new Error(`File not found in storage: ${stub.name}`);
              }
              return stirlingFile;
            }),
          );

          onStirlingFilesSelect(stirlingFiles);
          clearSelection();
        } catch (error) {
          console.error("Failed to load selected files:", error);
          throw error;
        }
      };

      return {
        toggleSelection,
        clearSelection,
        selectMultipleFiles,
      };

View on GitHub (pinned to 9ef20dcab8)

Solutions

Filter missing files out and proceed with the available subset, warning the user which files were dropped, rather than failing the whole selection.
Validate selection against storage on selection change and prune unselectable stubs immediately.
Raise the LRU cap if eviction is the frequent cause.
Surface the missing file names in the error message for recoverability.

Example fix

// before
const stirlingFiles = await Promise.all(
  selectedFileObjects.map(async (stub) => {
    const stirlingFile = await fileStorage.getStirlingFile(stub.id);
    if (!stirlingFile) throw new Error(`File not found in storage: ${stub.name}`);
    return stirlingFile;
  }),
);

// after — drop missing, report which were skipped
const results = await Promise.all(
  selectedFileObjects.map(async (stub) => ({ stub, file: await fileStorage.getStirlingFile(stub.id) })),
);
const stirlingFiles = results.filter(r => r.file).map(r => r.file);
const missing = results.filter(r => !r.file).map(r => r.stub.name);
if (stirlingFiles.length === 0) throw new Error(`No selected files are available in storage: ${missing.join(", ")}`);
if (missing.length) console.warn("Skipped missing files:", missing);
onStirlingFilesSelect(stirlingFiles);

Defensive patterns

Strategy: fallback

Validate before calling

// Validate the selection against storage before acting
const checked = await Promise.all(
  selectedFileObjects.map(async (stub) => ({ stub, ok: stub.id ? await fileStorage.hasFile?.(stub.id) : false })),
);
if (checked.some(c => !c.ok)) {
  // warn which files are missing; proceed with available subset or abort
}

Type guard

function isStirlingFile(f: StirlingFile | null | undefined): f is StirlingFile { return !!f; }

Try / catch

try {
  await selectMultipleFiles(files, onStirlingFilesSelect);
} catch (e) {
  if (e instanceof Error && e.message.startsWith("File not found in storage:")) {
    // list missing names, offer to re-add; proceed with available subset
  } else throw e;
}

Prevention

Validate selection against storage on selection change and prune unselectable stubs.
Drop missing files and proceed with the available subset instead of failing the whole selection.
Raise the LRU cap if eviction is the frequent cause.

When it happens

Trigger: Selected stubs were evicted from storage between selection and the 'use selected files' action; storage cleared mid-session; stale selection state restored pointing at deleted ids; concurrent operation deleted one of the selected files.

Common situations: User selects several files, waits, then acts after LRU eviction removed some; a remove-file action raced with selection; restored selection from a prior session.

Related errors

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/45196f46c3cd3d85. Report an issue: GitHub.