apache/skywalking · error · IllegalArgumentException

Unknown log field: log.{firstName}. Supported metadata field

Error message

Unknown log field: log.{firstName}. Supported metadata fields: {metadataGetters}, LogData fields: {logGetters}

What it means

Thrown at LAL compile time when log.<field> is used and <field> is neither a LogMetadata field (service, serviceInstance, endpoint, layer, timestamp, traceContext) nor a LogData field (body, tags). The message lists the exact supported key sets from LALCodegenHelper.METADATA_GETTERS and LOG_GETTERS, so it doubles as documentation.

Source

Thrown at oap-server/analyzer/log-analyzer/src/main/java/org/apache/skywalking/oap/log/analyzer/v2/compiler/LALValueCodegen.java:929

            return;
        }

        String current;
        boolean needsBoxing = false;
        String boxType = null;

        // Determine root based on first field
        final LALScriptModel.ValueAccessSegment first = chain.get(0);
        if (!(first instanceof LALScriptModel.FieldSegment)) {
            current = LOGDATA_BUILDER_CAST;
        } else {
            final String firstName = ((LALScriptModel.FieldSegment) first).getName();
            if (LALCodegenHelper.METADATA_GETTERS.containsKey(firstName)) {
                current = "h.ctx().metadata()";
            } else if (LALCodegenHelper.LOG_GETTERS.containsKey(firstName)) {
                current = LOGDATA_BUILDER_CAST;
            } else {
                throw new IllegalArgumentException(
                    "Unknown log field: log." + firstName
                        + ". Supported metadata fields: "
                        + LALCodegenHelper.METADATA_GETTERS.keySet()
                        + ", LogData fields: "
                        + LALCodegenHelper.LOG_GETTERS.keySet());
            }
        }

        for (int i = 0; i < chain.size(); i++) {
            final LALScriptModel.ValueAccessSegment seg = chain.get(i);
            if (seg instanceof LALScriptModel.FieldSegment) {
                final String name = ((LALScriptModel.FieldSegment) seg).getName();
                if (i == 0 && LALCodegenHelper.METADATA_GETTERS.containsKey(name)) {
                    if ("traceContext".equals(name)) {
                        current = current + ".getTraceContext()";
                    } else {
                        current = current + "."
                            + LALCodegenHelper.METADATA_GETTERS.get(name) + "()";

View on GitHub (pinned to 102af09b4a)

Solutions

Use one of the metadata fields: log.service, log.serviceInstance, log.endpoint, log.layer, log.timestamp, log.traceContext
Use one of the LogData fields: log.body, log.tags
For trace fields, chain through log.traceContext.traceId / traceSegmentId / spanId
If you need a body sub-value, parse it with json{}/yaml{}/text{} and use parsed.*

Example fix

# before
service log.serviceName as String

# after
service log.service as String

Defensive patterns

Strategy: validation

Validate before calling

# Supported first segments (fixed sets in LALCodegenHelper):
# metadata: service, serviceInstance, endpoint, layer, timestamp, traceContext
# logData:  body, tags
# Verify rule fields against these lists before deploy:
#   grep -oE 'log\.[A-Za-z]+' my-rule.yaml | sort -u

Prevention

Copy log.* paths from shipped lal/*.yaml examples rather than guessing
Use tag("KEY") for tags, parsers for body content
Add a CI lint step that checks log.* segments against the fixed set

When it happens

Trigger: log.serviceName, log.bodyText, log.tracecontext (wrong case), log.timestampMillis — any first path segment outside the two getter maps; also method-style chains whose first element is not a FieldSegment get defaulted into the LogData cast path and then fail this check.

Common situations: Guessing field names instead of checking the grammar; casing mistakes (log.Service); assuming v1 Groovy dynamic property lookup still works in the v2 typed compiler.

Related errors

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/2974d3714a8f24c9. Report an issue: GitHub.