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

The route contains invalid paths

Error message

The route contains invalid paths

What it means

Route::getRoutePaths() is the normalizer behind route path handling: it accepts null (empty paths), a string in 'Controller::action' or 'Module::Controller::action' short syntax (parsed into an array), or an already-built array. Anything else falls through the else-branch, stays non-array, and throws InvalidRoutePaths. This guards every route-creation entry point (add/addGet/addPost/... and group adds) at definition time.

Source

Thrown at phalcon/Mvc/Router/Route.zep:563

                        let routePaths["namespace"] = namespaceName;
                    }
                } else {
                    let realClassName = controllerName;
                }

                let routePaths["controller"] = realClassName;
            }

            // Process action name
            if actionName !== null {
                let routePaths["action"] = actionName;
            }
        } else {
            let routePaths = paths;
        }

        if unlikely typeof routePaths !== "array" {
            throw new InvalidRoutePaths();
        }

        return routePaths;
    }

    /**
     * Allows to set a callback to handle the request directly in the route
     *
     *```php
     * $router->add(
     *     "/help",
     *     []
     * )->match(
     *     function () {
     *         return $this->getResponse()->redirect("https://support.google.com/", true);
     *     }
     * );
     *```

View on GitHub (pinned to b7419de9cd)

Solutions

1. Pass an associative array: $router->add('/x', ['controller' => 'index', 'action' => 'hello']);
2. Or the short string: $router->add('/x', 'Index::hello');
3. Decode config arrays with json_decode(..., true) and cast nested path objects to arrays before registration

Example fix

// before
$router->add('/hello', $config->helloPaths); // value is stdClass/"Index::hello" object or scalar

// after
$paths = is_object($config->helloPaths)
    ? $config->helloPaths->toArray()
    : $config->helloPaths;
$router->add('/hello', $paths); // array or 'Index::hello' string

function isAcceptablePaths(mixed $paths): bool
{
    return $paths === null
        || is_array($paths)
        || (is_string($paths) && str_contains($paths, '::'));
}

try {
    $router->add($pattern, $paths);
} catch (\Phalcon\Mvc\Router\Exceptions\InvalidRoutePaths $e) {
    $logger->error(
        'Invalid paths for pattern ' . $pattern . ': ' . get_debug_type($paths)
    );
    throw $e;
}

When it happens

Trigger: $router->add('/x', 123); $router->add('/x', false); passing a stdClass/Config object as paths; passing null is fine, but a resource or float is not; feeding an object because config was decoded without the associative flag.

Common situations: Variables interpolated from config where a missing key defaulted to a scalar; booleans used as flags accidentally passed as the second argument; JSON-decoded route paths arriving as stdClass instead of array.

Related errors

• Wrong key in paths: {part}
• The not-found paths must be an array or string
• Route config entry is missing 'pattern'
• Route config entry is missing 'paths'
• Group route entry is missing 'pattern'

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