What causes "Please specify a valid URL" in octobercms/october?

Enter the full absolute URL including scheme, e.g. https://example.com (a path suffix is allowed)

octobercms/october · warning · October\Rain\Exception\ValidationException

Please specify a valid URL

Error message

Please specify a valid URL

What it means

The multisite SiteDefinition model validates in beforeValidate(): when a site is configured with a custom URL (is_custom_url), app_url must pass Url::isValidUrl() (scheme + host). Otherwise a ValidationException is thrown against the app_url field, so the backend site form redisplays with the field error instead of saving.

Source

Thrown at modules/system/models/SiteDefinition.php:129

            'name' => 'Primary Site',
            'code' => 'english',
            'is_primary' => true,
            'is_enabled' => true,
            'is_enabled_edit' => true,
            'group_id' => null,
            'group' => null,
        ];
        $site->syncOriginal();
        return $site;
    }

    /**
     * beforeValidate
     */
    public function beforeValidate()
    {
        if ($this->is_custom_url && !Url::isValidUrl($this->app_url)) {
            throw new ValidationException(['app_url' => __("Please specify a valid URL")]);
        }

        if ($this->is_prefixed && (substr($this->route_prefix, 0, 1) !== '/' || $this->route_prefix === '/')) {
            throw new ValidationException(['route_prefix' => __("Route prefix must start with a forward slash (/)")]);
        }

        if ($this->is_host_restricted && !$this->isAllowHostsValid()) {
            throw new ValidationException(['allow_hosts' => __("Please specify a valid hostname")]);
        }

        $this->fallback_locale = $this->getFallbackLocale($this->locale);
    }

    /**
     * getFallbackLocale attempts to extract the fallback language from the locale.
     * @return string
     */
    protected function getFallbackLocale($locale)

View on GitHub (pinned to b608633a7e)

Solutions

Enter the full absolute URL including scheme, e.g. https://example.com (a path suffix is allowed)
Disable the custom URL option if the site should derive its URL from the primary domain instead
When saving programmatically, set app_url from a normalized value (rtrim scheme+host) before save()

Example fix

# before
app_url: "example.com/de"

# after
app_url: "https://example.com/de"

Defensive patterns

Strategy: validation

Validate before calling

if ($site->is_custom_url && !\Url::isValidUrl($site->app_url)) {
    // block save and prompt for a full URL such as https://example.com
}

Prevention

Always include the scheme (https://) in custom site URLs
Normalize pasted URLs in the form (trim whitespace, add scheme) before submit
Turn off custom URL when the site can derive its URL from the primary domain

When it happens

Trigger: Saving a site with is_custom_url enabled and app_url lacking the scheme ('example.com', 'example.com/de'), empty, or otherwise malformed (spaces, smart quotes, invalid host).

Common situations: Entering a bare domain in the site form; pasting URLs with whitespace or unicode quotes; scripts provisioning sites with unnormalized URLs.

Related errors

AI-assisted analysis of octobercms/october@b608633a7e (2026-08-21). Data as JSON: /api/errors/97010a3c4c9a1e5b. Report an issue: GitHub.