mongodb/laravel-mongodb · error · InvalidArgumentException

Please pass a valid MongoDB command

Error message

Please pass a valid MongoDB command

What it means

The database-query-mongodb MCP tool received an empty `command` argument object. The tool runs MQL commands against a MongoDB connection, so the first key of the command document is the operation name; with no keys at all there is nothing to run. The library throws InvalidArgumentException before dispatching anything to the server.

Solutions

1. Pass a non-empty MQL command document as `command`, with the operation as the first key, e.g. {"find": "users", "filter": {"active": true}}.
2. Verify the MCP client/request actually serializes the `command` argument (check for typos like `commands` or `query`).
3. Remember this tool takes MQL, never SQL; do not pass a string like `db.users.find()` — build the document form.

Example fix

// before
{"connection": "mongodb", "command": {}}
// after
{"connection": "mongodb", "command": {"find": "users", "filter": {"active": true}}}

if (empty($command) || !is_array($command)) {
    throw new \InvalidArgumentException('command must be a non-empty MQL command document');
}

$isValid = is_array($command) && $command !== [] && is_string(array_key_first($command));

When it happens

Trigger: Calling the tool with `command` missing, or explicitly passing an empty array/object (e.g. `command: []` or `{}`), so that handleMql receives `$command === []` at src/Tools/DatabaseQuery.php:105.

Common situations: MCP client drops or sends an empty `command` field; a code generator builds the arguments dynamically and the command object ends up empty; a template/variable interpolating the command is unset; confusion with SQL-style tools where you pass a query string instead of a command document.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Only read commands are allowed
• Aggregation nesting exceeds the maximum of
• A pipeline exceeds the maximum of
• Only read aggregation stages are allowed. Found
• Database is not properly configured.

AI-assisted analysis of mongodb/laravel-mongodb@0634653039 (2026-09-15). Data as JSON: /api/errors/2ba4bf5c41f0a9eb. Report an issue: GitHub.

Appendix: source

Thrown at src/Tools/DatabaseQuery.php:106

            return Response::json($this->handleMql($request->array('command'), $connection));
        } catch (InvalidArgumentException $exception) {
            return Response::error($exception->getMessage());
        } catch (Throwable $exception) {
            return Response::error('Query failed: ' . $exception->getMessage());
        }
    }

    /**
     * @param array<string, mixed> $command
     *
     * @return array<int, mixed>
     *
     * @throws InvalidArgumentException
     */
    private function handleMql(array $command, Connection $connection): array
    {
        if ($command === []) {
            throw new InvalidArgumentException('Please pass a valid MongoDB command');
        }

        // Allowed CRUD commands (https://www.mongodb.com/docs/manual/reference/mql/crud-commands/)
        $allowList = ['aggregate', 'count', 'distinct', 'find'];
        $operation = array_key_first($command);

        if (! in_array($operation, $allowList, true)) {
            throw new InvalidArgumentException(sprintf('Only read commands are allowed (%s).', implode(', ', $allowList)));
        }

        if ($operation === 'aggregate') {
            // Check nested write ops recursively with conservative allow list
            $this->ensureNoNestedWriteInAggregation($command['pipeline'] ?? []);
        }

        return $connection->getDatabase()->command($command)->toArray();
    }

View on GitHub (pinned to 0634653039)