Prefix match in Nginx - Step-by-Step Execution

Process Flow - Prefix match

Request URL arrives

↓

Check location blocks

↓

Match prefix location?

↓

Serve content or proxy

Nginx checks the request URL against location blocks using prefix matching to find the best matching path prefix.

Execution Sample

Nginx

location /images/ {
    root /data;
}

location / {
    root /var/www/html;
}

This config serves URLs starting with /images/ from /data, others from /var/www/html.

Process Table

Step	Request URL	Location Tested	Prefix Match?	Action Taken
1	/images/cat.png	/images/	Yes	Select this location
2	/images/cat.png	/	Yes	Keep searching for longer prefix
3	/images/cat.png	No more locations	N/A	Serve from /images/ location root /data
4	/about.html	/images/	No	Skip this location
5	/about.html	/	Yes	Select this location
6	/about.html	No more locations	N/A	Serve from / location root /var/www/html

💡 Nginx picks the longest matching prefix location or default location if no prefix matches.

Status Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
Selected Location	None	/images/	/images/	/images/	/images/
Request URL	/images/cat.png	/images/cat.png	/images/cat.png	/images/cat.png	/images/cat.png

Key Moments - 2 Insights

Why does nginx continue checking other locations after finding a prefix match?

Nginx looks for the longest prefix match, so even if a prefix matches early (like '/'), it keeps checking for a longer prefix (like '/images/') as shown in steps 1 and 2.

What happens if no prefix matches the request URL?

Nginx uses the default location (usually '/') to serve the request, as shown in steps 4 to 6 for '/about.html'.

Visual Quiz - 3 Questions

Look at the execution table, which location is selected for the URL '/images/cat.png'?

A No location

B /images/

C /

D /about/

💡 Hint

Check steps 1 to 3 in the execution table where '/images/' is selected as the longest prefix match.

At which step does nginx decide to serve content from the '/' location for '/about.html'?

A Step 6

B Step 4

C Step 5

D Step 3

💡 Hint

Look at steps 4 to 6 where '/images/' is skipped and '/' is selected finally.

If a new location 'location /images/cat/' is added, how would the execution table change for '/images/cat.png'?

A It would select '/'

B It would still select '/images/'

C It would select '/images/cat/' as the longest prefix match

D It would cause an error

💡 Hint

Longest prefix match means the most specific prefix wins, so '/images/cat/' would be chosen.

Concept Snapshot

Nginx prefix match:
- Checks request URL against location prefixes
- Chooses longest matching prefix
- If none match, uses default location
- Example: /images/ matches URLs starting with /images/
- Order matters only for regex, prefix matches longest prefix wins

Full Transcript

When nginx receives a request URL, it checks all location blocks to find the best prefix match. It starts by testing each location's prefix against the URL. If a prefix matches, nginx remembers it but continues checking for a longer prefix match. If no longer prefix is found, nginx uses the best match to serve content. If no prefix matches, it uses the default location, usually '/'. For example, a request to '/images/cat.png' matches both '/' and '/images/', but nginx selects '/images/' because it is longer and more specific. This process ensures requests are routed to the correct content folder or proxy target.

Practice

1. What does prefix match in nginx do when routing requests?

easy

A. It matches requests based on the start of the URL path.

B. It matches requests only if the full URL matches exactly.

C. It matches requests based on the file extension.

D. It matches requests randomly to any location block.

Solution

1. Step 1: Understand prefix match concept

   Prefix match means nginx checks if the URL path starts with a specific string.

2. Step 2: Compare with other matching types

   Exact match requires full URL match, file extension match is unrelated, random match is invalid.

3. Final Answer:

   It matches requests based on the start of the URL path. -> Option A

4. Quick Check:

   Prefix match = start of URL path [OK]

Hint: Prefix match checks URL start, not full or random [OK]

Common Mistakes:

• Confusing prefix match with exact match
• Thinking prefix match checks file extensions
• Assuming prefix match is random

2. Which of the following is the correct syntax for a prefix match location in nginx?

easy

A. location = /images/ { }

B. location ^~ /images/ { }

C. location /images/ { }

D. location ~ /images/ { }

Solution

1. Step 1: Identify prefix match syntax

   Prefix match uses plain location /prefix/ { } without modifiers.

2. Step 2: Understand other modifiers

   = is exact match, ^~ is prefix but with higher priority, ~ is regex match.

3. Final Answer:

   location /images/ { } -> Option C

4. Quick Check:

   Plain location = prefix match [OK]

Hint: Plain location block means prefix match [OK]

Common Mistakes:

• Using = or ^~ modifiers for simple prefix match
• Confusing regex (~) with prefix match
• Missing trailing slash in prefix

3. Given this nginx config snippet:

location /app/ {
  proxy_pass http://backend1;
}
location /app/api/ {
  proxy_pass http://backend2;
}

Which backend will handle a request to /app/api/users?

medium

A. Both backends in round-robin

B. http://backend2

C. No backend, 404 error

D. http://backend1

Solution

1. Step 1: Understand prefix match selection

   nginx selects the location with the longest matching prefix for plain prefix locations (no modifiers).

2. Step 2: Compare prefixes

   Both /app/ (length 5) and /app/api/ (length 9) match /app/api/users, but /app/api/ is longer, so it wins.

3. Final Answer:

   http://backend2 -> Option B

4. Quick Check:

   Longest prefix wins [OK]

Hint: Longest matching prefix wins [OK]

Common Mistakes:

• Thinking config order (first match) wins instead of longest prefix
• Thinking regex or exact match applies here
• Believing nginx load balances both backends

4. You wrote this nginx config:

location /static {
  root /var/www/html;
}

Requests to /static/css/style.css return 404. What is the likely error?

medium

A. root directive path is incorrect

B. location block should use = modifier

C. Missing trailing slash in location prefix

D. proxy_pass is missing

Solution

1. Step 1: Understand root directive behavior

   root appends the full request URI (/static/css/style.css) to /var/www/html, looking for /var/www/html/static/css/style.css.

2. Step 2: Identify likely cause

   If static files are at /var/www/html/css/style.css (without static/), root path doesn't strip prefix, causing 404. (Use alias /var/www/html; to strip.)

3. Final Answer:

   root directive path is incorrect -> Option A

4. Quick Check:

   root + full URI (no prefix strip) [OK]

Hint: root appends full URI; alias strips prefix [OK]

Common Mistakes:

• Confusing root (full URI) with alias (strips prefix)
• Thinking trailing slash strips prefix for root
• Adding unnecessary modifiers like =

5. You want nginx to route all requests starting with /api/ to http://backend_api and all others to http://backend_web, ensuring the /api/ prefix has priority even if regex locations follow. Which config correctly uses prefix match for this?

hard

A. location ~ /api/ {
proxy_pass http://backend_api;
}
location / {
proxy_pass http://backend_web;
}

B. location /api/ {
proxy_pass http://backend_api;
}
location / {
proxy_pass http://backend_web;
}

C. location = /api/ {
proxy_pass http://backend_api;
}
location / {
proxy_pass http://backend_web;
}

D. location ^~ /api/ {
proxy_pass http://backend_api;
}
location / {
proxy_pass http://backend_web;
}

Solution

1. Step 1: Use ^~ for prefix priority

   The ^~ modifier tells nginx to stop searching if prefix matches, ensuring /api/ routes to backend_api even over later regex.

2. Step 2: Default location for others

   The plain location / { } catches all other requests to backend_web.

3. Final Answer:

   location ^~ /api/ { proxy_pass http://backend_api; } location / { proxy_pass http://backend_web; } -> Option D

4. Quick Check:

   ^~ prefix match for priority routing [OK]

Hint: Use ^~ to prioritize prefix match over regex [OK]

Common Mistakes:

• Not using ^~ causes regex or exact match to override
• Using = modifier limits to exact /api/ only
• Using ~ makes it regex, not prefix match