Custom plugin - request field is nil?

I’m trying to learn about developing a custom plugin and have found several articles people have written showing how to begin with a simple example. I’ve taken the example schema.lua and handler.lua files and am able to load these into Kong and apply the plugin to a test service. However, they both seem to fail when attempting to access the request object, for example:

self.echo_string = kong.request.get_header(conf.requestHeader)

In the Kong log is this error message:

2019/10/25 18:39:50 [error] 24#0: *2316 lua coroutine: runtime error: .../custom/kong/plugins/kong-plugin-header-echo/handler.lua:20: attempt to index field 'request' (a nil value)

This would seem to indicate that the ‘request’ object is invalid or that it cannot be used in this manner. I’ve read through the Kong documentation about writing handler.lua, but it doesn’t go into details about the inherent objects with which your code would interact. The suggested link to code for the key-auth plugin shows this using the kong.request object, but not using a get_header() method.

Are these inherent object types more fully documented somewhere? I’m trying this with Kong EE 0.34-1.


Kong Enterprise 0.34 is based on Kong 0.13, which predates the PDK (I’m assuming the “request” in question is, along with a number of other changes to the plugin development environment. covers development on 0.34. Because the PDK is not available, plugins will generally use lua-nginx-module functions directly, e.g. as in

Thanks for your response, and for the info on the difference in plug-in models. Will take a look at the links you’ve shared.

I understand that internally, Kong supports code written to Lua v5.1, but I’ve been having challenges getting a viable development environment on my Mac as it seems the tools are all geared towards Lua v5.3. Would you be at liberty to share what tools you use for plug-in development?

Plugin development generally requires an instance of Kong itself, since plugins aren’t designed for standalone execution. The Kong Vagrant provides one of those as a VM image, and will work well for most scenarios. Note that you’ll want to install whichever Kong version you use; the VM comes with the latest community release.

Once that’s in place, the simplest way to start testing with your plugin is to drop its folder in /usr/local/share/lua/5.1/kong/plugins/ and add its name to

From there you can add it to routes/services/etc. via the admin API as with any bundled plugin.