The error occurs because the mod_vhost_alias module isn't loaded in your Apache configuration. Unlike regular DocumentRoot, VirtualDocumentRoot is part of this special module designed for mass virtual hosting environments.

Run this command to verify module status:

apache2ctl -M | grep vhost_alias
# or for httpd:
httpd -M | grep vhost_alias

For Debian/Ubuntu systems:

sudo a2enmod vhost_alias
sudo systemctl restart apache2

For RHEL/CentOS systems:

# Edit httpd.conf and ensure this line exists:
LoadModule vhost_alias_module modules/mod_vhost_alias.so
sudo systemctl restart httpd

Here's a fully functional virtual host configuration using VirtualDocumentRoot:

    ServerName wildcard.mydomain.com
    ServerAlias *.mydomain.com
    VirtualDocumentRoot /var/www/vhosts/%1/public_html
    VirtualScriptAlias /var/www/vhosts/%1/cgi-bin
    
    
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    
    
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined

The module supports several pattern replacements:

%0 - the whole name
%1 - first part
%2 - second part
%-1 - last part
%2+ - second part and all remaining parts

If you still encounter problems:

1. Verify Apache version compatibility (works on 2.2+)
2. Check directory permissions match the user Apache runs as
3. Ensure SELinux/AppArmor isn't blocking access
4. Confirm the parent directory (/var/www/vhosts) exists

---

When attempting to restart Apache, you encountered the error:

Invalid command 'VirtualDocumentRoot', perhaps misspelled or defined by a module not included in the server configuration
Action 'start' failed.

This typically occurs when attempting to use the VirtualDocumentRoot directive without the required Apache module being enabled.

The VirtualDocumentRoot directive is part of Apache's mod_vhost_alias module. This module isn't enabled by default in many Apache installations. Your configuration snippet:

<VirtualHost *:80>
    ServerAdmin help@mydomain.com
    VirtualDocumentRoot /local/www/staging/%1
    
    ServerAlias *.staging.mydomain.com
</VirtualHost>

works on another server because that server likely has mod_vhost_alias enabled.

The solution is to enable the required module. Here's how to do it on different systems:

For Debian/Ubuntu:

sudo a2enmod vhost_alias
sudo systemctl restart apache2

For CentOS/RHEL:

sudo yum install mod_vhost_alias
sudo systemctl restart httpd

If you can't use mod_vhost_alias, you can achieve similar functionality with standard VirtualHost directives:

<VirtualHost *:80>
    ServerName project1.staging.mydomain.com
    DocumentRoot /local/www/staging/project1
    # Other directives...
</VirtualHost>

<VirtualHost *:80>
    ServerName project2.staging.mydomain.com
    DocumentRoot /local/www/staging/project2
    # Other directives...
</VirtualHost>

After enabling the module, verify it's loaded:

apache2ctl -M | grep vhost
# Or for httpd:
httpd -M | grep vhost

You should see vhost_alias_module (shared) in the output.

The VirtualDocumentRoot directive becomes powerful when combined with other mod_vhost_alias features:

<VirtualHost *:80>
    ServerName staging.mydomain.com
    ServerAlias *.staging.mydomain.com
    
    # Match subdomains to directories
    VirtualDocumentRoot /local/www/staging/%-2+
    
    # Log files per subdomain
    CustomLog /var/log/apache2/access_staging_%1.log combined
    ErrorLog /var/log/apache2/error_staging_%1.log
</VirtualHost>

This configuration automatically maps project.staging.mydomain.com to /local/www/staging/project.

• Check Apache error logs for additional details: /var/log/apache2/error.log or /var/log/httpd/error_log
• Verify file permissions on the document root directories
• Ensure SELinux contexts are correct if using SELinux
• Test configuration before restarting: apachectl configtest