phalcon/cphalcon · error · Phalcon\Mvc\Router\Exceptions\MissingGroupRouteKey

Group route entry is missing 'paths'

Error message

Group route entry is missing 'paths'

What it means

Every group route definition must also carry a 'paths' key with the controller/action map for that route; its absence inside a group's routes entry throws MissingGroupRouteKey('paths').

Source

Thrown at phalcon/Mvc/Router.zep:2149

        if isset groupData["hostname"] {
            group->setHostname((string) groupData["hostname"]);
        }

        if !fetch routes, groupData["routes"] {
            let routes = [];
        }

        if typeof routes !== "array" {
            throw new GroupRoutesMustBeArray();
        }

        for routeData in routes {
            if !fetch pattern, routeData["pattern"] {
                throw new MissingGroupRouteKey("pattern");
            }
            if !fetch routePaths, routeData["paths"] {
                throw new MissingGroupRouteKey("paths");
            }

            let method = "";
            if isset routeData["method"] && routeData["method"] !== null {
                let method = strtolower((string) routeData["method"]);
            }

            switch method {
                case "":
                case "connect":
                case "delete":
                case "get":
                case "head":
                case "options":
                case "patch":
                case "post":
                case "purge":
                case "put":

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add "paths": {"controller": "dashboard", "action": "index"} to the entry
2. Use exactly the key 'paths'
3. Run a config validator before loadFromConfig that walks groups[].routes[] and checks both keys

Example fix

// before
"routes": [
    {"pattern": "/dashboard"}
]

// after
"routes": [
    {
        "pattern": "/dashboard",
        "paths": {"controller": "dashboard", "action": "index"}
    }
]

foreach ($config['groups'] ?? [] as $g => $group) {
    foreach ($group['routes'] ?? [] as $i => $entry) {
        if (!is_array($entry) || !array_key_exists('paths', $entry)) {
            throw new InvalidArgumentException("groups[$g].routes[$i] is missing 'paths'");
        }
    }
}

$router->loadFromConfig($config);

function groupRouteEntryIsValid(mixed $entry): bool
{
    return is_array($entry)
        && array_key_exists('pattern', $entry)
        && array_key_exists('paths', $entry);
}

try {
    $router->loadFromConfig($config);
} catch (\Phalcon\Mvc\Router\Exceptions\MissingGroupRouteKey $e) {
    $logger->error('Group route entry rejected: ' . $e->getMessage());
    throw $e;
}

When it happens

Trigger: Group route entry with only {"pattern": "/dashboard"}; key named "defaults" or "target" instead of "paths"; empty-object entry from a template.

Common situations: Same as top-level missing 'paths' but within the groups section; assuming the group prefix supplies destinations; converting group code to config and forgetting the second argument's equivalent.

Related errors

• Group route entry is missing 'pattern'
• 'groups' must be an array
• Route config entry is missing 'pattern'
• Route config entry is missing 'paths'
• Group 'routes' must be an array

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