{"record":{"id":"60edd587a0d1b6a5","repo":"JuliusBrussee/caveman","slug":"unknown-target-column-q-not-a-caveman-spans-colu","errorCode":null,"errorMessage":"unknown target column %q (not a caveman.spans column)","messagePattern":"unknown target column %q \\(not a caveman\\.spans column\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shared/platform/importers/generic.go","lineNumber":96,"sourceCode":"\t\t\tresolvedTargets[target] = true\n\t\t}\n\t\trows = append(rows, sp)\n\t}\n\tfor target, path := range opts.FieldMap {\n\t\tif !resolvedTargets[target] {\n\t\t\treturn nil, fmt.Errorf(\"mapped source path %q for target %q was not found in any record\", path, target)\n\t\t}\n\t}\n\treturn rows, nil\n}\n\nfunc validateGenericFieldMap(fieldMap map[string]string) error {\n\tif len(fieldMap) == 0 {\n\t\treturn fmt.Errorf(\"generic import requires a non-empty field map\")\n\t}\n\tfor target, path := range fieldMap {\n\t\tif _, ok := genericTargets[target]; !ok {\n\t\t\treturn fmt.Errorf(\"unknown target column %q (not a caveman.spans column)\", target)\n\t\t}\n\t\tif strings.TrimSpace(path) == \"\" {\n\t\t\treturn fmt.Errorf(\"generic target %q requires a non-empty source path\", target)\n\t\t}\n\t}\n\tfor _, target := range []string{\"trace_id\", \"span_id\", \"timestamp\"} {\n\t\tif _, ok := fieldMap[target]; !ok {\n\t\t\treturn fmt.Errorf(\"generic import requires a %q mapping\", target)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc decodeGenericRecords(data []byte) ([]map[string]any, error) {\n\t// Try a bare array first.\n\tvar arr []map[string]any\n\tif err := json.Unmarshal(data, &arr); err == nil {\n\t\treturn arr, nil","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/shared/platform/importers/generic.go#L78-L114","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the target against the importer's supported columns (the genericTargets set in shared/platform/importers/generic.go).","Rename the map key to the exact snake_case column name (e.g. traceId -> trace_id).","Remove mappings for columns the importer does not have; unsupported data cannot be forced in via an unknown target.","Unit-test your field map against validateGenericFieldMap before shipping config."],"exampleFix":"// before\nFieldMap: map[string]string{\"traceId\": \"ctx.trace\"}\n\n// after\nFieldMap: map[string]string{\"trace_id\": \"ctx.trace\"}","handlingStrategy":"type-guard","validationCode":"allowed := map[string]bool{ /* copy from importers.genericTargets */ \"trace_id\": true, \"span_id\": true, \"timestamp\": true }\nfor target := range fieldMap {\n    if !allowed[target] { return fmt.Errorf(\"unknown target %q\", target) }\n}","typeGuard":"func knownTarget(target string, allowed map[string]bool) bool { return allowed[target] }","tryCatchPattern":"if err := importers.ImportGeneric(data, opts); err != nil {\n    return err // rename the target in the message to its snake_case spans column\n}","preventionTips":["Author field maps using the spans schema, not the source system's field names.","Use snake_case target keys exclusively.","Validate maps against genericTargets in a unit test shipped with your config."],"tags":["go","import","field-mapping","validation"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}