JuliusBrussee/caveman · error

unknown target column %q (not a caveman.spans column)

Error message

unknown target column %q (not a caveman.spans column)

What it means

Thrown by validateGenericFieldMap (generic.go:96): a FieldMap key is not present in the genericTargets set, i.e. it is not a recognized caveman.spans column. Targets are a closed vocabulary, so mapping onto an invented column name is a configuration error caught before any records are processed. The offending target is included in the message.

Source

Thrown at shared/platform/importers/generic.go:96

			resolvedTargets[target] = true
		}
		rows = append(rows, sp)
	}
	for target, path := range opts.FieldMap {
		if !resolvedTargets[target] {
			return nil, fmt.Errorf("mapped source path %q for target %q was not found in any record", path, target)
		}
	}
	return rows, nil
}

func validateGenericFieldMap(fieldMap map[string]string) error {
	if len(fieldMap) == 0 {
		return fmt.Errorf("generic import requires a non-empty field map")
	}
	for target, path := range fieldMap {
		if _, ok := genericTargets[target]; !ok {
			return fmt.Errorf("unknown target column %q (not a caveman.spans column)", target)
		}
		if strings.TrimSpace(path) == "" {
			return fmt.Errorf("generic target %q requires a non-empty source path", target)
		}
	}
	for _, target := range []string{"trace_id", "span_id", "timestamp"} {
		if _, ok := fieldMap[target]; !ok {
			return fmt.Errorf("generic import requires a %q mapping", target)
		}
	}
	return nil
}

func decodeGenericRecords(data []byte) ([]map[string]any, error) {
	// Try a bare array first.
	var arr []map[string]any
	if err := json.Unmarshal(data, &arr); err == nil {
		return arr, nil

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Check the target against the importer's supported columns (the genericTargets set in shared/platform/importers/generic.go).
2. Rename the map key to the exact snake_case column name (e.g. traceId -> trace_id).
3. Remove mappings for columns the importer does not have; unsupported data cannot be forced in via an unknown target.
4. Unit-test your field map against validateGenericFieldMap before shipping config.

Example fix

// before
FieldMap: map[string]string{"traceId": "ctx.trace"}

// after
FieldMap: map[string]string{"trace_id": "ctx.trace"}

allowed := map[string]bool{ /* copy from importers.genericTargets */ "trace_id": true, "span_id": true, "timestamp": true }
for target := range fieldMap {
    if !allowed[target] { return fmt.Errorf("unknown target %q", target) }
}

func knownTarget(target string, allowed map[string]bool) bool { return allowed[target] }

if err := importers.ImportGeneric(data, opts); err != nil {
    return err // rename the target in the message to its snake_case spans column
}

When it happens

Trigger: FieldMap contains a key like "traceId" (camelCase instead of snake_case), "durationMs", or any column that is not in genericTargets; validation iterates the map and returns on the first unknown key.

Common situations: Field maps authored from an external system's field names instead of the spans schema; casing conventions drifting between systems; an attempted mapping for a column the importer does not support; typos.

Related errors

• generic target %q requires a non-empty source path
• generic record %d: %w
• mapped source path %q for target %q was not found in any rec
• generic import requires a non-empty field map
• generic import requires a %q mapping

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/60edd587a0d1b6a5. Report an issue: GitHub.