conductor-oss/conductor · error · IllegalArgumentException

Skill file is too large to preview: {cleanPath}

Error message

Skill file is too large to preview: {cleanPath}

What it means

Thrown by readFile() when the matched zip entry's reported size (entry.getSize()) exceeds maxPreviewBytes (default 1,048,576 = 1 MiB, configurable via agentspan.skills.max-preview-bytes). This is the fast pre-read size check that avoids loading a large file into memory. It uses the zip central-directory size, so it triggers before any byte is streamed.

Source

Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/SkillRegistryService.java:279

        requireSkillStorage();
        if (path == null || path.isBlank()) {
            throw new IllegalArgumentException("File path is required");
        }
        String cleanPath = normalizeEntryName(path);
        SkillDetail detail = get(name, version);
        byte[] packageBytes = packageBytes(detail);
        try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(packageBytes))) {
            ZipEntry entry;
            while ((entry = zip.getNextEntry()) != null) {
                if (entry.isDirectory()) {
                    continue;
                }
                String entryName = normalizeEntryName(entry.getName());
                if (!entryName.equals(cleanPath)) {
                    continue;
                }
                if (entry.getSize() > maxPreviewBytes) {
                    throw new IllegalArgumentException(
                            "Skill file is too large to preview: " + cleanPath);
                }
                byte[] data =
                        readBounded(
                                zip,
                                maxPreviewBytes,
                                "Skill file is too large to preview: " + cleanPath);
                boolean binary = isBinary(cleanPath, data);
                return SkillFileContent.builder()
                        .path(cleanPath)
                        .contentType(contentType(cleanPath))
                        .size(data.length)
                        .binary(binary)
                        .content(binary ? null : new String(data, StandardCharsets.UTF_8))
                        .contentBase64(binary ? Base64.getEncoder().encodeToString(data) : null)
                        .build();
            }
            throw new IllegalArgumentException("Skill file not found: " + cleanPath);

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Download the full package instead of previewing: GET /api/skills/{name}/versions/{version}/package.
2. Raise agentspan.skills.max-preview-bytes in application config if previewing large files is intended.
3. Move large files out of the skill package, or split them so the previewed entry is under the limit.

Example fix

# before (preview blocked on >1MiB entry)
GET /api/skills/foo/versions/1.0.0/files?path=assets/large.bin
# after (download full package instead)
GET /api/skills/foo/versions/1.0.0/package

// Client-side: check the entry size from the skill detail before previewing
SkillDetail d = skillRegistryService.get(name, version);
SkillFileEntry entry = d.getFiles().stream()
    .filter(f -> f.getPath().equals(path)).findFirst().orElseThrow();
if (entry.getSize() > maxPreviewBytes) { /* use package download instead */ }

static boolean isPreviewable(SkillFileEntry e, long maxPreviewBytes) {
    return e.getSize() >= 0 && e.getSize() <= maxPreviewBytes;
}

try { return skillRegistryService.readFile(name, version, path); }
catch (IllegalArgumentException e) {
    if (e.getMessage().contains("too large to preview")) { return downloadPackageInstead(name, version); }
    throw e;
}

When it happens

Trigger: GET /api/skills/{name}/versions/{version}/files?path=assets/big-image.png where the entry size is > 1 MiB. Fires when previewing a large bundled asset, data file, or oversized doc.

Common situations: Skills that bundle large reference datasets or images; lowering max-preview-bytes in config then previewing previously-readable files; a skill author committing a multi-MB asset into the package root.

Related errors

• Skill package exceeds max size of {maxPackageBytes} bytes
• Skill package exceeds max file count of {maxFileCount}
• Skill package contains oversized file: {path}
• Skill package exceeds max uncompressed size of {maxUncompres
• Skill manifest name '{manifestName}' does not match package

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