What causes "Arguments must be an array or string, {type} given" in phalcon/cphalcon?

Cast scalars before calling: $router->handle((string) $arguments)

phalcon/cphalcon · error · Phalcon\Cli\Router\Exceptions\RouterArgumentsInvalidType

Arguments must be an array or string, {type} given

Error message

Arguments must be an array or string, {type} given

What it means

Cli\Router::handle() accepts arguments only as an array (typically $_SERVER['argv']), a string, or null. Any other type — int, float, bool, object — throws RouterArgumentsInvalidType, with the actual gettype() of the value embedded in the message.

Source

Thrown at phalcon/Cli/Router.zep:239

     *
     * @phpstan-param mixed $arguments
     */
    public function handle(arguments = null)
    {
        var moduleName, taskName, actionName, params, route, parts, pattern,
            routeFound, matches, paths, beforeMatch, converters, converter,
            part, position, matchPosition, strParams;

        let routeFound = false,
            parts = [],
            params = [],
            matches = null,
            this->wasMatched = false,
            this->matchedRoute = null;

        if typeof arguments !== "array" {
            if unlikely (typeof arguments != "string" && arguments !== null) {
                throw new RouterArgumentsInvalidType(gettype(arguments));
            }

            for route in reverse this->routes {
                /**
                 * If the route has parentheses use preg_match
                 */
                let pattern = route->getCompiledPattern();

                if memstr(pattern, "^") {
                    let routeFound = preg_match(pattern, arguments, matches);
                } else {
                    let routeFound = pattern == arguments;
                }

                /**
                 * Check for beforeMatch conditions
                 */
                if routeFound {

View on GitHub (pinned to b7419de9cd)

Solutions

Cast scalars before calling: $router->handle((string) $arguments)
Pass the raw argv array: $router->handle($_SERVER['argv'] ?? null)
Pass null to reset the router state intentionally

Example fix

// before
$router->handle($argc);

// after
$router->handle($_SERVER['argv'] ?? null);

Defensive patterns

Strategy: type-guard

Validate before calling

$arguments = $_SERVER['argv'] ?? null;
if ($arguments !== null && !is_array($arguments) && !is_string($arguments)) {
    throw new InvalidArgumentException(sprintf(
        'Router arguments must be array|string|null, %s given',
        gettype($arguments)
    ));
}
$router->handle($arguments);

Type guard

/**
 * Cli\Router::handle() accepts only array, string, or null.
 */
function isRouterArguments($value): bool
{
    return $value === null || is_string($value) || is_array($value);
}

Try / catch

try {
    $router->handle($arguments);
} catch (\Phalcon\Cli\Router\Exception\RouterArgumentsInvalidType $e) {
    // Message names the actual type received; coerce and retry once with a string
    $router->handle((string) $arguments);
}

Prevention

Pass $_SERVER['argv'] (or null) instead of derived scalar values
Cast any computed string-ish scalar with (string) before handle()
Remember objects with __toString do not pass — convert them explicitly

When it happens

Trigger: $router->handle(3) passing a count, handle(true), or handle(new ArrayObject($argv)) — objects with __toString are also rejected because the check is on typeof, not on convertibility.

Common situations: Passing a normalized/computed value that silently became a non-string scalar (e.g. an option count or exit code instead of the arguments); passing an argv wrapper object; passing $_GET into a CLI router by copy-paste.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/7e2e45f6919961fc. Report an issue: GitHub.