cowboy:set_env - Update a listener's environment value


set_env(Name  :: ranch:ref(),
        Key   :: atom(),
        Value :: any())
    -> ok

Set or update an environment value for a previously started listener.

This is most useful for updating the routes dynamically, without having to restart the listener.

The new value will only be available to new connections. Pre-existing connections will still use the old value.



The name of the listener to update.

The name of the listener is the first argument given to the cowboy:start_clear(3), cowboy:start_tls(3) or ranch:start_listener(3) function.


The key in the environment map. Common keys include dispatch and middlewares.


The new value.

The type of the value differs depending on the key.

Return value

The atom ok is returned on success.

An exit:badarg exception is thrown when the listener does not exist.


  • 1.0: Function introduced.


Update a listener's routes
Dispatch = cowboy_router:compile([
    {'_', [
        {"/", toppage_h, []},
        {"/ws", websocket_h, []}

cowboy:set_env(example, dispatch, Dispatch).

See also

cowboy(3), cowboy:start_clear(3), cowboy:start_tls(3), ranch:set_protocol_options(3)

Cowboy 2.10 Function Reference


Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.