Apache mod_alias Takes Priority Over mod_proxy

When an Alias /path /var/www/html/path directive and a ProxyPass /path/ directive target the same URL prefix, Apache's mod_alias hooks earlier in the request processing chain than mod_proxy. If the physical directory exists on disk, Alias wins silently — API requests under that prefix are never proxied.

Key Points

mod_alias runs at the URL translation phase — earlier than mod_proxy in Apache's hook chain
When a physical directory matching the Alias exists on disk, Alias wins for ALL requests under that prefix
ProxyPass /path/api/ never fires — silent failure, no Apache error, no 502
Fix option 1: use RewriteRule [P,L] for API paths, placed BEFORE the Alias directive
Fix option 2: serve static files from a different path than the proxy prefix
This only affects cases where the static directory actually exists — if the directory is absent, Alias is a no-op and ProxyPass works

Details

The Conflict Pattern

# Static files under /video-accessibility/
Alias /video-accessibility /var/www/html/video-accessibility

# API proxy under same prefix — NEVER FIRES when directory exists
ProxyPass /video-accessibility/api/ http://127.0.0.1:8042/api/
ProxyPassReverse /video-accessibility/api/ http://127.0.0.1:8042/api/

Apache's processing order for this config:

URL translation phase: Alias runs → matches /video-accessibility/* → resolves to filesystem path
mod_proxy phase: never reached for requests under /video-accessibility/

Fix 1: RewriteRule with [P,L] for API Paths

# Place BEFORE the Alias directive
RewriteEngine On
RewriteRule ^/video-accessibility/api/(.*)$ http://127.0.0.1:8042/api/$1 [P,L]

# Static files — now only catches non-API paths
Alias /video-accessibility /var/www/html/video-accessibility

The [P] flag (proxy) and [L] flag (last rule, stop processing) together replicate ProxyPass behaviour. RewriteRule runs at the fixups stage and can override alias translation when declared first.

Fix 2: Separate Paths

# Static files at /video-accessibility/ (Alias)
Alias /video-accessibility /var/www/html/video-accessibility

# API at a completely different path prefix
ProxyPass /video-accessibility-api/ http://127.0.0.1:8042/api/

This avoids the conflict entirely but requires updating frontend API call paths.

Diagnosis

If ProxyPass rules appear correct but API calls return static HTML (or 404s from the filesystem):

Check if an Alias directive covers the same prefix
Verify the physical directory exists: ls /var/www/html/<path>
If both exist, you have this conflict

wiki/concepts/apache-proxypass-include-files-ignored — related Apache silent failure: ProxyPass in Include fragments ignored
wiki/architecture/optical-dev-server-deploy — optical-dev Apache vhost pattern, Alias and ProxyPass layout

Sources

daily/2026-04-30.md — Sessions 15:45 and 15:59, mod_alias winning over mod_proxy for video-accessibility

3.3 KiB Raw Blame History