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

Route config entry is missing 'pattern'

Error message

Route config entry is missing 'pattern'

What it means

While processing entries from config['routes'] (via loadFromConfig -> addRouteFromConfig), each entry must contain a 'pattern' key defining the URI pattern to match. If the first fetch of routeData['pattern'] fails (key absent or null), MissingRouteConfigKey('pattern') is thrown naming the missing key.

Source

Thrown at phalcon/Mvc/Router.zep:2061

     */
    public function wasMatched() -> bool
    {
        return this->wasMatched;
    }

    /**
     * Adds a single route from a config array entry. Used by loadFromConfig.
     *
     * @param array routeData
     *
     * @return void
     */
    protected function addRouteFromConfig(array routeData) -> void
    {
        var method, methodClass, pattern, paths, route;

        if !fetch pattern, routeData["pattern"] {
            throw new MissingRouteConfigKey("pattern");
        }

        if !fetch paths, routeData["paths"] {
            throw new MissingRouteConfigKey("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":

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add the pattern: {"pattern": "/api/users", "paths": {"controller": "users", "action": "index"}}
2. Check spelling of the key — it must be exactly 'pattern' (lowercase)
3. Pre-validate every routes[] entry contains both 'pattern' and 'paths' before loadFromConfig so the error names the file and index

Example fix

// before
{
    "routes": [
        {"paths": {"controller": "users", "action": "index"}}
    ]
}

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

// verify required keys per route entry before loading
foreach ($config['routes'] ?? [] as $i => $entry) {
    if (!is_array($entry) || !array_key_exists('pattern', $entry)) {
        throw new InvalidArgumentException("routes[$i] is missing 'pattern'");
    }
    if (!array_key_exists('paths', $entry)) {
        throw new InvalidArgumentException("routes[$i] is missing 'paths'");
    }
}

$router->loadFromConfig($config);

function routeEntryIsValid(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\MissingRouteConfigKey $e) {
    // message names the missing key ('pattern' or 'paths')
    $logger->error('Route config entry rejected: ' . $e->getMessage());
    throw $e;
}

When it happens

Trigger: A route entry like {"paths": {"controller": "users"}} with no "pattern"; pattern misspelled ("patterns", "route", "uri"); entry reduced to an empty object by a merge or an if-block that never set it.

Common situations: Hand-written YAML/JSON route files with inconsistent keys; config templates where the pattern line was commented out; code generators emitting a subset of keys.

Related errors

• Route config entry is missing 'paths'
• Group route entry is missing 'pattern'
• Group route entry is missing 'paths'
• loadFromConfig requires an array or Phalcon\Config\ConfigInt
• 'defaults' must be an array

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