conductor-oss/conductor · error · NotFoundException

File not found: {}

Error message

File not found: {}

What it means

Thrown by getFileModelOrThrow when fileMetadataDAO.getFileMetadata returns null for the given fileId. No file record exists for that id, so any file operation is rejected. Raised as NotFoundException (HTTP 404). This is the root lookup failure underlying all file endpoints.

Source

Thrown at core/src/main/java/org/conductoross/conductor/core/storage/FileStorageServiceImpl.java:254

    /** Downloads and metadata are visible to the owning workflow's full workflow family. */
    private @NonNull FileModel getFamilyAccessibleFile(String workflowId, String fileId) {
        FileModel model = getFileModelOrThrow(fileId);
        if (model.getWorkflowId() == null || model.getWorkflowId().isBlank()) {
            throw new AccessForbiddenException("File has no workflowId: " + fileId);
        }

        Set<String> family = workflowFamilyResolver.getFamily(workflowId);
        if (!family.contains(model.getWorkflowId())) {
            throw new AccessForbiddenException("Workflow cannot access file: " + fileId);
        }
        return model;
    }

    private FileModel getFileModelOrThrow(String fileId) {
        FileModel model = fileMetadataDAO.getFileMetadata(fileId);
        if (model == null) {
            throw new NotFoundException("File not found: " + fileId);
        }
        return model;
    }
}

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Verify the fileId is complete and was returned by a prior createFile call.
2. Confirm the file was not deleted in the target environment.
3. Ensure you are not passing a fileHandleId where the raw fileId is required (check converter semantics).
4. List/search file metadata to locate the correct id.

Example fix

// before - using a stale/wrong id
fileStorageService.getDownloadUrl(wfId, "abc"); // 404

// after - use the id returned at creation
FileUploadResponse r = fileStorageService.createFile(req);
fileStorageService.getDownloadUrl(wfId, r.getFileId());

FileModel model = fileMetadataDAO.getFileMetadata(fileId);
if (model == null) { /* do not call file endpoints */ }

try {
    fileStorageService.getDownloadUrl(wfId, fileId);
} catch (NotFoundException e) {
    // no such file record
}

When it happens

Trigger: Any file endpoint called with a fileId that was never created, was deleted, or is malformed. E.g. getDownloadUrl/confirmUpload/uploadContent/downloadContent/getFileMetadata with an unknown fileId.

Common situations: Stale/truncated fileId; file was deleted; wrong environment/cluster; typo; using a fileHandleId where a fileId is expected (note the FileIdToFileHandleIdConverter mapping).

Related errors

• Skill file not found: {cleanPath}
• No such taskType found by name: %s
• No such workflow found by name: %s, version: %d
• Workflow with id: %s not found.
• conductor.file-storage.conductor.signing.keys is required wh

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/898b3d7c2771f595. Report an issue: GitHub.