APISIX: Consumer Empty After Plugin Association? Solved!

Hey guys, ever encountered a situation in APISIX where you create and associate a plugin with a consumer, but the code retrieves the consumer as empty? It's a tricky situation, but let's dive into the details and figure out what might be going on and how to fix it. This article will explore a common issue encountered when working with plugins and consumers in APISIX, specifically when the consumer information is not being retrieved correctly after a plugin is associated with it. We'll break down the problem, examine the code, analyze the logs, and provide potential solutions to help you troubleshoot and resolve this issue.

The Problem: Empty Consumer Retrieval

So, the core issue is that after creating a consumer and associating a plugin (in this case, ale-key-auth-consumer) through the APISIX dashboard, the code within the plugin is unable to retrieve the consumer's configuration. This results in an error, as the plugin relies on this configuration to function correctly. Let's break down the scenario:

1. A consumer is created in the APISIX dashboard.
2. The ale-key-auth-consumer plugin is bound to this consumer.
3. When a request is made that triggers the plugin, the plugin's code attempts to retrieve the consumer's configuration using consumer_mod.plugin(plugin_name).
4. However, this function returns nil, indicating that the consumer configuration cannot be found.

This leads to the plugin being unable to validate the request, resulting in a 401 error with the message "Missing related consumer." This can be frustrating, but let's dig deeper to understand why this might be happening.

Analyzing the Code: The ale-key-auth-consumer Plugin

Let's take a closer look at the provided Lua code for the ale-key-auth-consumer plugin. This will help us understand how it's supposed to work and where the problem might lie.

local core = require("apisix.core")
local consumer_mod = require("apisix.consumer")

-- Plugin metadata and configuration schema
local plugin_name = "ale-key-auth-consumer"

-- Route schema
local schema = {
    type = "object",
    properties = {
        header = {
            type = "string",
            default = "apikey",
        },
        query = {  -- New: Field name to get the key from the query parameters (default apikey)
            type = "string",
            default = "apikey",
        }
    }
}

-- Consumer schema
local consumer_schema = {
    type = "object",
    properties = {
        key = {
            type = "string",
            minLength = 1,
        },
    },
    required = {"key"}
}

local _M = {
    version = 0.1,
    priority = 2500,
    name = plugin_name,
    schema = schema,
    consumer_schema = consumer_schema,
}

function _M.check_schema(conf, schema_type)
    if schema_type == core.schema.TYPE_CONSUMER then
        return core.schema.check(consumer_schema, conf)
    else
        return core.schema.check(schema, conf)
    end
}

function _M.rewrite(conf, ctx)
    -- Get from request header first
    local from_header = true
    local key = core.request.header(ctx, conf.header)
    core.log.warn("Key from request header: ", key)

    if not key then
        local uri_args = core.request.get_uri_args(ctx) or {}
        key = uri_args[conf.query]
        from_header = false
    end

    if not key then
        return 401, {message = "Missing API key found in request"}
    end

    local consumer_conf = consumer_mod.plugin(plugin_name)
    local consumer_conf_str = consumer_conf and core.json.encode(consumer_conf) or "nil"
    core.log.warn("Consumer config: " .. consumer_conf_str .. "，Plugin name：" .. plugin_name)
    if not consumer_conf then
        return 401, {message = "Missing related consumer"}
    end

    local consumers = consumer_mod.consumers_kv(plugin_name, consumer_conf, "key")
    local consumer = consumers[key]
    if not consumer then
        return 401, {message = "Invalid API key in request"}
    end
    core.log.warn("consumer: ", core.json.delay_encode(consumer))

    consumer_mod.attach_consumer(ctx, consumer, consumer_conf)
    core.log.warn("hit ale-key-auth rewrite")
end

return _M

Here's a breakdown of the key parts:

• plugin_name: Defines the name of the plugin (ale-key-auth-consumer).
• schema and consumer_schema: Define the schemas for the plugin and consumer configurations, respectively. These schemas ensure that the configurations are valid.
• _M.rewrite(conf, ctx): This is the main function that handles the plugin's logic. It retrieves the API key from the request (either from the header or query parameters), retrieves the consumer configuration, validates the key, and attaches the consumer to the context.
• consumer_mod.plugin(plugin_name): This is the crucial line where the consumer configuration is retrieved. It uses the consumer_mod module to fetch the configuration associated with the plugin name.

The core of the issue lies in why consumer_mod.plugin(plugin_name) is returning nil. Let's explore some possible reasons.

Analyzing the Logs: Spotting the Issue

The provided error log snippet gives us a crucial clue:

2025/11/09 09:17:49 [warn] 55#55: *273968 [lua] ale-key-auth-consumer.lua:59: phase_func(): Key from request header: 000, client: 172.18.0.1, server: _, request: "GET /api/hello HTTP/1.1", host: "172.28.160.1:9080"
2025/11/09 09:17:49 [warn] 55#55: *273968 [lua] ale-key-auth-consumer.lua:73: phase_func(): Consumer config: nil，Plugin name：ale-key-auth-consumer, client: 172.18.0.1, server: _, request: "GET /api/hello HTTP/1.1", host: "172.28.160.1:9080"

This log clearly shows that the consumer_conf is nil when consumer_mod.plugin(plugin_name) is called. This confirms our suspicion that the consumer configuration is not being retrieved correctly.

Possible Causes and Solutions

Now that we understand the problem and have analyzed the code and logs, let's explore the potential causes and their solutions:

1. Incorrect Plugin Association

• Cause: The plugin might not be correctly associated with the consumer in the APISIX dashboard. It's possible that the association was not saved properly, or there might be a misconfiguration.
• Solution: Double-check the APISIX dashboard to ensure that the ale-key-auth-consumer plugin is indeed associated with the correct consumer. Remove the association and re-add it to ensure it's correctly configured. Verify that the consumer is enabled and that the plugin is enabled on the route or service.

2. Caching Issues

• Cause: APISIX uses caching to improve performance. It's possible that the consumer configuration is not being updated in the cache after the plugin association. This could lead to the old (or non-existent) configuration being retrieved.
• Solution: Try invalidating the cache. You can do this by restarting APISIX or by using the APISIX Admin API to clear the cache for consumers. This will force APISIX to fetch the latest configuration.

3. Etcd Synchronization Problems

• Cause: APISIX uses etcd as its configuration store. If there are synchronization issues between the APISIX instances and etcd, the consumer configuration might not be propagated correctly.
• Solution: Check the etcd logs for any errors or warnings related to synchronization. Ensure that the etcd cluster is healthy and that all APISIX instances can communicate with it. You might need to restart APISIX instances or the etcd cluster to resolve synchronization issues.

4. Plugin Loading Order

• Cause: In rare cases, the order in which plugins are loaded might affect their ability to access consumer configurations. If the ale-key-auth-consumer plugin is loaded before the consumer module is fully initialized, it might not be able to retrieve the configuration.
• Solution: While less likely, you can try adjusting the plugin loading order in the APISIX configuration. However, this is usually not the primary cause and should be considered as a last resort.

5. Code Errors in Other Plugins

• Cause: It's possible that another plugin is interfering with the consumer retrieval process. If another plugin has an error that affects the shared context or data structures, it could prevent consumer_mod.plugin(plugin_name) from working correctly.
• Solution: Disable other plugins one by one to see if the issue resolves. This will help you identify if another plugin is the culprit. Check the logs for other plugins for any errors or warnings.

6. Incorrect Plugin Name

• Cause: A simple but often overlooked mistake is using an incorrect plugin name when calling consumer_mod.plugin(). If the name doesn't match the actual plugin name, the configuration won't be found.
• Solution: Double-check the plugin name used in the code (plugin_name) and ensure it exactly matches the name used when associating the plugin with the consumer in the APISIX dashboard. They must be identical.

7. Issues with consumer_mod Module

• Cause: There might be an issue within the consumer_mod module itself. This is less likely, but it's worth considering if all other solutions fail.
• Solution: Check the APISIX core logs for any errors or warnings related to the consumer_mod module. You might need to consult the APISIX documentation or community for known issues or bugs related to this module. Upgrading APISIX to the latest version might also resolve potential bugs.

Debugging Steps

To effectively troubleshoot this issue, follow these steps:

1. Verify Plugin Association: Double-check the APISIX dashboard to confirm the plugin is correctly associated with the consumer.
2. Check Logs: Analyze the APISIX error logs and warning logs for any clues. Look for errors related to consumer retrieval, etcd communication, or other plugins.
3. Restart APISIX: Restarting APISIX can often resolve caching or synchronization issues.
4. Clear Cache: If restarting doesn't help, try clearing the APISIX cache.
5. Examine etcd: Check the etcd logs and health status to ensure it's functioning correctly.
6. Disable Other Plugins: Temporarily disable other plugins to rule out any interference.
7. Verify Plugin Name: Ensure the plugin name used in the code matches the name used in the dashboard.
8. Consult Documentation and Community: If you're still stuck, consult the APISIX documentation and community forums for help.

Applying the Solutions to the Case

In the provided scenario, the logs clearly indicate that consumer_conf is nil. This suggests that the plugin is unable to retrieve the consumer configuration. Given the possible causes we've discussed, the most likely scenarios are:

• Incorrect Plugin Association: It's possible that the plugin was not correctly associated with the consumer in the APISIX dashboard.
• Caching Issues: The consumer configuration might not be updated in the cache.

The first step would be to verify the plugin association in the dashboard. If that's correct, try restarting APISIX or clearing the cache. If the issue persists, investigate etcd synchronization and consider disabling other plugins to rule out interference.

Conclusion

Encountering an empty consumer retrieval in APISIX after associating a plugin can be a frustrating issue. However, by understanding the code, analyzing the logs, and systematically exploring the possible causes and solutions, you can effectively troubleshoot and resolve the problem. Remember to double-check plugin associations, consider caching and etcd issues, and don't hesitate to consult the APISIX documentation and community for help. By following these steps, you'll be back on track to building robust and secure APIs with APISIX. Good luck, and happy coding!