Trouble with simple custom module


I’m playing with caddy and trying to implement a custom module. I followed the docs and successfully setup an environment with xcaddy. I used this as a starting point: Extending Caddy — Caddy Documentation

I created a “Gizmo” module but used the ID: “http.handlers.gizmo”. I see it listed when I run

xcaddy list-modules.

However, I get an error with the following Caddyfile:


root * static

When I do xcaddy adapt && xcaddy run at the command line I get the error:

adapt: Caddyfile:4: unrecognized directive: gizmo

Is there something more I need to do to make my gizmo available as a directive?



Hi Dave, welcome!

You’ll need to register your directive. You can call RegisterDirective() (or RegisterHandlerDirective()) in init() somewhere to do that.

Make sure to read these docs about extending the HTTP Caddyfile, specifically this section about directives:

Also the next section about directive ordering is important. HTTP handlers are invoked in a certain order during requests, but it’s (unfortunately) impossible to properly put an extension’s directive in order unless it’s manually configured. So even though you register your directive, you’ll either have to add an order global option to the top of your Caddyfile or use it only within route { } blocks. The linked docs should explain this.

(We probably could make this more discoverable, but the introductory “Extending Caddy” tutorial is about modules generally and doesn’t go into specifics for different kinds of modules, like HTTP handlers. So I’m not sure how to improve the docs in that sense.)

Hope that helps.


Hi, Matt,

Thank you for taking the time to answer. This is exactly what I needed to know!

We probably could make this more discoverable...

Speaking from the POV of a caddy newbie the docs are excellent. The only suggestion I can think to make would be to include the error message on that page. That would give google a fighting chance at finding it.

Thanks again,


This topic was automatically closed after 30 days. New replies are no longer allowed.