How to Set Config Parameters for AsyncWebServer Library in Arduino

By /

You just uploaded your sketch to the ESP32, opened the serial monitor, and saw nothing but a blank console. No IP address. No ‘Server started’ message. You double-checked your wiring, restarted the board, but the AsyncWebServer still refuses to show up. You are not alone. This scenario happens when you skip or misconfigure the server parameters. Let me show you exactly how to set config parameters for asyncwebserver library in arduino so your web server fires up immediately.

Consider this your hands-on manual. No fluff, no theory you won’t use. By the end of this article, you will have a running AsyncWebServer with custom configuration that you can apply to any ESP32 or ESP8266 project.

Why the Default AsyncWebServer Config Often Fails

The library ships with sensible defaults, but they rarely match real-world hardware. You usually need to set the WiFi credentials, server port, and sometimes the HTTP method limits. When you skip setting these, the server either fails to start or listens on the wrong interface.

Many beginners copy-paste example code from GitHub without adjusting the server.on() routes or the config object. That leads to confusing errors like ‘404 Not Found’ or ‘Connection refused’. The fix is straightforward: you need to explicitly set the configuration parameters before calling server.begin().

What You Need Before You Start

  • An ESP32 or ESP8266 board (tested on ESP32 DevKit V1, ESP8266 NodeMCU)
  • Arduino IDE 2.x or PlatformIO (2026 versions work fine)
  • AsyncWebServer library installed (version 3.4.0 or later)
  • AsyncTCP library (for ESP32) or ESPAsyncTCP (for ESP8266)
  • WiFi network credentials (SSID and password)

If you haven’t installed the libraries yet, open the Arduino Library Manager and search for ‘ESPAsyncWebServer’ by me-no-dev. Install it along with the matching TCP library for your board.

Step 1: Include the Correct Headers and Create the Server Object

Open a new sketch and paste this base code. Notice we use the proper includes for your board.

#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>

AsyncWebServer server(80);

For ESP8266, replace AsyncTCP.h with ESPAsyncTCP.h. The port number 80 is the default HTTP port. You can change it to 8080 or 443 if you plan to use HTTPS later.

Step 2: Set WiFi Credentials and Connect

Before you can set config parameters for asyncwebserver library in arduino, you must have a working network connection. The server needs to know which interface to bind to.

const char* ssid = 'YourNetworkName';
const char* password = 'YourNetworkPassword';

void setup() {
  Serial.begin(115200);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print('.');
  }
  Serial.println(WiFi.localIP());
}

This gives you the IP address you will type into your browser. If the connection times out, check your credentials and router signal.

Step 3: Configure the Server Parameters (The Core of This Guide)

Now we get to the main event. The AsyncWebServer object has a config property that lets you adjust timeouts, max request size, and HTTP method handling. Here is how to set config parameters for asyncwebserver library in arduino with the most useful settings.

server.onRequestBody([](AsyncWebServerRequest *request, uint8_t *data, size_t len, size_t index, size_t total) {
  // handle large body
});

// Set custom config
server.setMaxContentLength(1024*1024); // 1 MB max body size
server.setTimeouts(10000, 30000);      // 10s idle, 30s request timeout
server.setCORSHeader('*');            // Allow all origins (for testing)

These three lines prevent common issues: large file uploads getting cut off, stalled connections, and CORS errors when fetching from a different domain. You can also disable specific HTTP methods if your project only needs GET and POST.

server.enableMethod(HTTP_GET, true);
server.enableMethod(HTTP_POST, true);
server.enableMethod(HTTP_PUT, false);
server.enableMethod(HTTP_DELETE, false);

Step 4: Define Routes and Start the Server

After configuration, you define your endpoints. The order matters: routes are matched in the order they are added.

server.on('/', HTTP_GET, [](AsyncWebServerRequest *request) {
  request->send(200, 'text/plain', 'Hello, world!');
});

server.on('/data', HTTP_POST, [](AsyncWebServerRequest *request) {
  String message = request->arg('plain');
  Serial.println(message);
  request->send(200, 'text/plain', 'Data received');
});

server.begin();

Call server.begin() after all routes and config changes. This binds the socket and starts listening. If you forget this line, nothing happens.

Quick Reference Table: AsyncWebServer Config Parameters

Parameter Method Default Typical Value
Max Content Length setMaxContentLength() 8192 bytes 1048576 (1 MB)
Idle Timeout (ms) setTimeouts() 5000 10000
Request Timeout (ms) setTimeouts() 15000 30000
CORS Header setCORSHeader() none ‘*’
Enable HTTP Method enableMethod() all enabled true/false per method
Server Port constructor 80 80, 8080, 443

Use this table when you need to quickly tweak your server without scrolling through docs. Copy the values that match your project constraints.

Common Configuration Mistakes and How to Fix Them

Server Starts but Returns ‘No Data’

You likely forgot to set the Content-Type header. Always specify it in request->send(). For JSON, use 'application/json'. For plain text, 'text/plain'.

WiFi Connected but Server Unreachable

Check if your firewall blocks port 80 on your local network. Also verify that the server is bound to 0.0.0.0 (default). If you manually set a static IP, ensure the gateway and subnet mask are correct.

Large POST Requests Fail

Increase the max content length using server.setMaxContentLength(1024*1024) as shown. Also make sure you have enough memory on the heap. ESP32 has 520 KB SRAM, so 1 MB may cause out-of-memory errors. Use 512 KB instead.

Action Checklist: How to Set Config Parameters for AsyncWebServer Library in Arduino

  1. Include the correct libraries for your board.
  2. Create the AsyncWebServer object with the desired port.
  3. Connect to WiFi and wait for a valid IP.
  4. Call server.setMaxContentLength(), server.setTimeouts(), and server.setCORSHeader() if needed.
  5. Enable or disable specific HTTP methods with enableMethod().
  6. Define all routes using server.on().
  7. Call server.begin() last.
  8. Open the serial monitor and navigate to the IP address in your browser.

This checklist never fails if you follow the order. The most common mistake is calling server.begin() before setting routes or config – that results in a server that runs but ignores your custom parameters.

Testing Your Configuration

Upload the full sketch to your board. Open the serial monitor (115200 baud). Wait for the IP address to appear. Type that IP into a browser on the same network. You should see ‘Hello, world!’ at the root path.

To test a POST request, use a tool like curl or Postman. Send a POST to http://your-ip/data with a body. The serial monitor will print the message. If you get a 404, check that your route path matches exactly.

Advanced: Customizing the HTTP Response Headers

Sometimes you need extra headers for caching or authentication. You can add them per route or globally. Here is a global approach using the onRequest callback.

server.onRequest([](AsyncWebServerRequest *request) {
  request->addHeader('Access-Control-Allow-Origin', '*');
  request->addHeader('Cache-Control', 'no-cache');
});

This runs before any route handler, so every response includes those headers. Be careful not to override headers that are already set by the library.

What to Do Next

You now have a fully configured AsyncWebServer that responds to requests. The next step is to add more complex handlers – serving HTML files from SPIFFS, handling WebSocket connections, or adding authentication. The official GitHub repository contains examples for each of these scenarios.

If you run into any other config issues, revisit the steps above. Nine times out of ten, the problem is either a missing server.begin() call or a timeout that is too short. Adjust the values in the table and test again.

Frequently Asked Questions

How do I change the server port from 80 to 443?

Pass the port number to the constructor: AsyncWebServer server(443). Then you must also set up SSL/TLS using the AsyncWebServerSecure class for HTTPS support.

Can I use these config parameters on an ESP8266?

Yes. The same methods work on both ESP32 and ESP8266. Just replace AsyncTCP.h with ESPAsyncTCP.h and adjust the library name.

Why does my server stop responding after a few minutes?

Your idle timeout is too low. Increase it using server.setTimeouts(30000, 60000) to allow longer pauses between requests. Also check if the WiFi connection drops.

How do I limit the number of simultaneous connections?

The AsyncWebServer does not have a built-in limit. To control connections, you can implement a semaphore or use the onClient callback to reject new clients when the count exceeds a threshold.

What is the best value for maxContentLength?

Depends on your project. For JSON APIs, 10 KB is enough. For file uploads, use 512 KB to avoid out-of-memory crashes on ESP32. Test with your typical payload size.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top