t8y2/dbx · error · java.lang.IllegalArgumentException

System collections cannot be cloned

Error message

System collections cannot be cloned

What it means

cloneCollection rejects any request whose source or target collection name starts with "system.", because MongoDB system collections are internal and must not be duplicated via user-driven clones. The check runs before any server-side work.

Source

Thrown at agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java:1163

        c.getDatabase(database).getCollection(collection).drop();
        return Collections.singletonMap("ok", true);
    }

    /**
     * Clone a regular collection with the commands available to the legacy
     * driver. This keeps older MongoDB servers on the same full-clone path as
     * the native driver instead of silently copying documents only.
     */
    private static Object cloneCollection(JsonObject params) {
        MongoClient client = requireClient();
        String databaseName = params.get("database").getAsString();
        String sourceName = params.get("source_collection").getAsString();
        String targetName = params.get("target_collection").getAsString();
        if (sourceName.equals(targetName)) {
            throw new IllegalArgumentException("Target collection name must differ from the source collection name");
        }
        if (sourceName.startsWith("system.") || targetName.startsWith("system.")) {
            throw new IllegalArgumentException("System collections cannot be cloned");
        }

        MongoDatabase database = client.getDatabase(databaseName);
        Document sourceSpecification = requireCollectionSpecification(database, sourceName);
        if (!isRegularCollectionSpecification(sourceSpecification)) {
            throw new IllegalArgumentException(
                "Only regular MongoDB collections can be cloned; views and time-series collections are not supported"
            );
        }

        Document collectionOptions = collectionOptions(sourceSpecification);
        // Explicit creation ensures the source is never merged into an
        // existing target collection.
        database.runCommand(cloneCreateCollectionCommand(targetName, sourceSpecification));

        MongoCollection<Document> source = database.getCollection(sourceName);
        MongoCollection<Document> target = database.getCollection(targetName);
        long documentsCopied = cloneCollectionDocuments(source, target, needsValidationBypass(collectionOptions));

View on GitHub (pinned to c0390bff16)

Solutions

1. Remove system.* collections from the input (clone user collections only)
2. Filter out names starting with 'system.' when enumerating collections programmatically
3. Use mongodump/mongorestore or $out for legitimate internal-data backup needs

Example fix

// before
params.addProperty("source_collection", "system.js");
params.addProperty("target_collection", "system_js_copy");
// after
String src = "system.js";
if (!src.startsWith("system.")) {
    params.addProperty("source_collection", src);
    params.addProperty("target_collection", src + "_copy");
}

if (sourceName.startsWith("system.") || targetName.startsWith("system.")) {
    throw new IllegalArgumentException("system.* collections cannot be cloned");
}

boolean isUserCollection(String name) {
    return name != null && !name.startsWith("system.");
}

try {
    agent.execute("cloneCollection", params);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("System collections")) {
        // skip or back up via mongodump instead
    } else { throw e; }
}

When it happens

Trigger: Passing source_collection or target_collection starting with "system." (e.g. "system.js", "system.views") to the cloneCollection action.

Common situations: Attempting to back up internal metadata collections like system.js; scripts iterating all collections returned by listCollections without filtering system.* entries; accidental typo prefixing a name with 'system.'.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• MongoDB aggregate option ${key} must be a non-negative integ
• MongoDB explain verbosity must be queryPlanner, executionSta
• Unsupported findOne option: ${key}
• Unsupported collation option: ${key}
• Invalid collation: locale must not be empty

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/b26db4b684d723ac. Report an issue: GitHub.