conductor-oss/conductor · error · IllegalArgumentException

Skill package contains oversized file: {path}

Error message

Skill package contains oversized file: {path}

What it means

Thrown by parseSkillPackage when a single file's uncompressed size exceeds maxPackageBytes (default 50 MiB) during streaming decompression. The size is accumulated per-entry as bytes are read, so it catches an entry whose decompressed content alone is too large, even if the compressed zip is small.

Source

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

                            "Skill package exceeds max file count of " + maxFileCount);
                }
                String path = normalizeEntryName(entry.getName());
                if (contentByPath.containsKey(path)) {
                    throw new IllegalArgumentException(
                            "Skill package contains duplicate path: " + path);
                }
                MessageDigest digest = MessageDigest.getInstance("SHA-256");
                long size = 0;
                ByteArrayOutputStream content = new ByteArrayOutputStream();
                byte[] buffer = new byte[8192];
                int read;
                while ((read = zip.read(buffer)) >= 0) {
                    digest.update(buffer, 0, read);
                    content.write(buffer, 0, read);
                    size += read;
                    totalUncompressedBytes += read;
                    if (size > maxPackageBytes) {
                        throw new IllegalArgumentException(
                                "Skill package contains oversized file: " + path);
                    }
                    if (totalUncompressedBytes > maxUncompressedBytes) {
                        throw new IllegalArgumentException(
                                "Skill package exceeds max uncompressed size of "
                                        + maxUncompressedBytes
                                        + " bytes");
                    }
                }
                contentByPath.put(path, content.toByteArray());
                files.add(
                        SkillFileEntry.builder()
                                .path(path)
                                .size(size)
                                .sha256(hex(digest.digest()))
                                .contentType(contentType(path))
                                .build());
            }

View on GitHub (pinned to cf7c3e4a8a)

Solutions

  1. Remove or shrink the oversized single file from the package.
  2. Split the large file into smaller chunks if it must be bundled.
  3. Reference large data externally rather than embedding it in the skill zip.

Example fix

// before: package includes a 120MB generated.json
// after: remove it, reference via URL in SKILL.md
zip skill.zip SKILL.md scripts/ references/small.json
Defensive patterns

Strategy: validation

Validate before calling

// Before zipping, check each candidate file's uncompressed size
for (Path p : includedFiles) {
    if (Files.size(p) > maxPackageBytes) throw new IllegalArgumentException("oversized file: " + p);
}

Type guard

static boolean noOversizedFile(long fileSize, long maxPackageBytes) { return fileSize <= maxPackageBytes; }

Try / catch

try { skillRegistryService.register(manifest, pkg); }
catch (IllegalArgumentException e) {
    if (e.getMessage().contains("oversized file")) { /* remove or shrink the file */ }
    else throw e;
}

Prevention

When it happens

Trigger: POST /api/skills/register with a zip containing one highly-compressible but huge file (e.g. a 200 MiB log or a generated JSON) that decompresses past the per-file cap. Distinguished from [94] (total) by being per-file.

Common situations: A skill bundling a single large generated reference file; a compressed text/log file that is small compressed but large decompressed; vendoring a big dataset as one file.

Related errors

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