JuliusBrussee/caveman · error

generic target %q requires a non-empty source path

Error message

generic target %q requires a non-empty source path

What it means

Thrown by validateGenericFieldMap (generic.go:99): a FieldMap entry has a known, valid target but its source path is empty after trimming. A target with no source path cannot resolve in any record, so it is rejected up front rather than failing later with the 'not found in any record' error. Both the target and its (empty) value would be meaningless.

Source

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

	}
	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
	}
	// Then a {"data":[...]} wrapper.
	var env struct {

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Fill in a real source path for the named target, or delete the entry entirely.
2. Guard your config loader: reject empty values for field-map entries before they reach the importer.
3. Watch YAML keys with no value - write key: "" explicitly or omit the key.
4. Re-run validateGenericFieldMap-equivalent checks locally before import.

Example fix

# before (yaml)
field_map:
  span_id:

# after
field_map:
  span_id: $.attributes.span.id

for target, path := range fieldMap {
    if strings.TrimSpace(path) == "" {
        return fmt.Errorf("target %q has an empty source path", target)
    }
}

func allPathsSet(m map[string]string) bool {
    for _, v := range m { if strings.TrimSpace(v) == "" { return false } }
    return true
}

if err := importers.ImportGeneric(data, opts); err != nil {
    return err // fill or remove the entry named in the message
}

When it happens

Trigger: FieldMap contains e.g. {"span_id": ""} or {"span_id": " "}; common when a config template defines all columns and some are left blank for the operator to fill, or when a YAML null deserializes as an empty string.

Common situations: Template configs with placeholder empty values never filled in; YAML keys with no value (key:) unmarshalling to ""; programmatic map building that sets a key before computing the path and never does; merge of config layers where one layer blanked the value.

Related errors

• mapped source path %q for target %q was not found in any rec
• generic import requires a non-empty field map
• unknown target column %q (not a caveman.spans column)
• invalid listen address %q: %w
• invalid listen port %q

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