JuliusBrussee/caveman · error

unknown import format %q: supported formats are otlp, cavema

Error message

unknown import format %q: supported formats are otlp, caveman-jsonl, langfuse, helicone, generic

What it means

Import dispatches on the format string and this default branch fires when the format matches none of FormatOTLP, FormatCavemanJSONL, FormatLangfuse, FormatHelicone, FormatGeneric. The comment marks it fail-closed by design: unknown formats are never silently passed through. The error enumerates the supported set so the caller can self-correct.

Source

Thrown at shared/platform/importers/importers.go:92

	}
	var (
		rows []Span
		err  error
	)
	switch format {
	case FormatOTLP:
		rows, err = parseOTLP(data, opts)
	case FormatCavemanJSONL:
		rows, err = parseCavemanJSONL(data, opts)
	case FormatLangfuse:
		rows, err = parseLangfuse(data, opts)
	case FormatHelicone:
		rows, err = parseHelicone(data, opts)
	case FormatGeneric:
		rows, err = parseGeneric(data, opts)
	default:
		// fail-closed: unknown formats are an error, never a silent pass-through.
		return nil, Summary{}, fmt.Errorf("unknown import format %q: supported formats are otlp, caveman-jsonl, langfuse, helicone, generic", format)
	}
	if err != nil {
		return nil, Summary{}, err
	}
	for i := range rows {
		if len(rows[i].EventsJSON) > telemetry.MaxEventsBytes {
			return nil, Summary{}, fmt.Errorf("sanitize row %d: events exceed %d bytes", i, telemetry.MaxEventsBytes)
		}
		sanitized, sanitizeErr := telemetry.SanitizeAttributes(rows[i].Attributes)
		if sanitizeErr != nil {
			return nil, Summary{}, fmt.Errorf("sanitize row %d: %w", i, sanitizeErr)
		}
		rows[i].Attributes = sanitized
	}
	return rows, Summary{Format: format, RowCount: len(rows)}, nil
}

// ---------------------------------------------------------------------------

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Use the exported Format* constants (importers.FormatOTLP etc.) instead of raw strings
2. If the string comes from user input, validate it against the allowed set before calling Import
3. Trim whitespace and lowercase the input if it originates from config
4. Upgrade the shared/platform package if you expect a format added in a newer version

Example fix

// before
rows, sum, err := importers.Import("otlp-json", data, opts)

// after
rows, sum, err := importers.Import(importers.FormatOTLP, data, opts)

var supportedFormats = map[string]bool{
	importers.FormatOTLP: true, importers.FormatCavemanJSONL: true,
	importers.FormatLangfuse: true, importers.FormatHelicone: true,
	importers.FormatGeneric: true,
}
func formatSupported(f string) bool { return supportedFormats[strings.TrimSpace(f)] }

func formatSupported(f string) bool {
	switch strings.TrimSpace(f) {
	case importers.FormatOTLP, importers.FormatCavemanJSONL, importers.FormatLangfuse,
		importers.FormatHelicone, importers.FormatGeneric:
		return true
	}
	return false
}

if !formatSupported(fmtStr) { return fmt.Errorf("unsupported format %q (typo?)", fmtStr) } rows, sum, err := importers.Import(fmtStr, data, opts)

When it happens

Trigger: Calling Import with an empty format string; passing 'json' or 'otlp-json' instead of the exact constants; case mismatch ('OTLP' vs 'otlp') since dispatch is exact-match on the constant values; passing a newly added format name not yet in this switch.

Common situations: Format taken from a CLI flag or HTTP header without validation; version skew where the caller knows a format this build doesn't; trailing whitespace in the format string; typo in configuration YAML.

Related errors

• unknown target column %q (not a caveman.spans column)
• generic target %q requires a non-empty source path
• generic import requires a %q mapping
• cachebench: nil corpus reader
• message exceeds byte limit

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