How to Fix Kong Plugin Installation and Runtime Error

In this tutorial, you'll learn about How to Fix Kong Plugin Installation and Runtime Error. We cover key concepts, practical examples, and best practices.

Kong plugin returns Error: plugin is not enabled or schema violation when applying plugin configuration — the plugin is not in the enabled list or the configuration does not match the plugin schema.

The Problem

Error: /usr/local/share/lua/5.1/kong/cmd/migrations.lua:48:
Schema violation (my-plugin.config):
  my-param: expected a string but got boolean

Step-by-Step Fix

Step 1: Enable the plugin in kong.conf

# /etc/kong/kong.conf
plugins = bundled,my-plugin

Step 2: Validate the plugin config

# Test the plugin configuration
curl -i -X POST http://localhost:8001/routes/{route-id}/plugins \
  --data "name=my-plugin" \
  --data "config.my-param=value"

Expected:

HTTP/1.1 201 Created

Step 3: Check plugin priority

-- custom-plugin/handler.lua
local MyPlugin = {
  VERSION = "1.0.0",
  PRIORITY = 1000
}

function MyPlugin:access(conf)
  kong.log.info("plugin executed")
end

Step 4: Debug with kong logs

tail -f /usr/local/kong/logs/error.log

Step 5: Restart after enabling

kong restart

Prevention Tips

• List enabled plugins with curl http://localhost:8001/plugins
• Test plugins in dev mode before production
• Use the Admin API to enable/disable plugins at runtime
• Validate Lua plugins with luacheck before loading

Common Mistakes with plugin error

1. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
2. Using return to exit a function early instead of wrapping a pure value in the monad
3. Mixing let bindings with <- bindings in do notation, producing type errors

These mistakes appear frequently in real-world KONG 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