How to Fix HAProxy ACL Configuration Error

In this tutorial, you'll learn about How to Fix HAProxy ACL Configuration Error. We cover key concepts, practical examples, and best practices.

HAProxy ACL rules do not match as expected — traffic is routed to the wrong backend or ACL conditions are silently ignored because of incorrect ordering or syntax.

The Problem

# Wrong: ACL is never matched because it is after the use_backend
frontend web
  use_backend api if api_path
  acl api_path path_beg /api

ACL must be defined before the use_backend line.

Step-by-Step Fix

Step 1: Declare ACLs before use_backend

frontend web
  bind *:80

  # Declare ACLs first
  acl is_api path_beg /api
  acl is_static path_end .css .js .png
  acl is_admin hdr(Host) -i admin.example.com

  # Then use them
  use_backend api_servers if is_api
  use_backend static_servers if is_static
  use_backend admin_servers if is_admin
  default_backend web_servers

Step 2: Use OR and AND conditions

# OR condition
use_backend secure_api if is_api is_authenticated

# AND condition (both must match)
use_backend secure_api if is_api is_authenticated

# Negation
use_backend public_api if is_api !is_authenticated

Step 3: Debug ACL matching

frontend web
  # Log the ACL results
  capture request header Host len 32
  http-request set-var(txn.acl_match) str("none")

  acl is_api path_beg /api
  http-request set-var(txn.acl_match) str("api") if is_api

  # Add to log
  log-format "%ci:%cp [%T] %f %b/%s %ST %B %[var(txn.acl_match)]"

Step 4: Test with curl

curl -H "Host: admin.example.com" http://localhost/admin/

Prevention Tips

• Always define ACLs before the first use_backend that references them
• Use meaningful ACL names and comment complex rules
• Test ACL logic with haproxy -f /etc/haproxy/haproxy.cfg -c for syntax validation
• Add option httplog for detailed request logging

Common Mistakes with acl error

1. Forgetting deriving (Show, Eq) on custom data types needed for debugging
2. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
3. Using head and tail instead of pattern matching, causing runtime errors on empty lists

These mistakes appear frequently in real-world HAPROXY code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ