Tencent/WeKnora · error

invalid fileName: path traversal or empty name

Error message

invalid fileName: path traversal or empty name

What it means

Guard in SafeFileName: after Clean and Base, the name reduces to '', '.', or '..', meaning the input carried no real file-name component or was pure traversal; the function refuses to return a usable name.

Source

Thrown at internal/utils/security.go:136

	if err != nil {
		return "", fmt.Errorf("invalid file path: %w", err)
	}
	sep := string(filepath.Separator)
	if absPath != absBase && !strings.HasPrefix(absPath, absBase+sep) {
		return "", fmt.Errorf("path traversal denied: path is outside base directory")
	}
	return absPath, nil
}

// SafeFileName 校验并返回安全的“仅文件名”部分，防止路径遍历。
// 仅保留最后一个路径成分，禁止 ".."、空名或仅含点，用于 SaveBytes 等场景。
func SafeFileName(fileName string) (string, error) {
	if fileName == "" {
		return "", fmt.Errorf("fileName cannot be empty")
	}
	base := filepath.Base(filepath.Clean(fileName))
	if base == "" || base == "." || base == ".." {
		return "", fmt.Errorf("invalid fileName: path traversal or empty name")
	}
	if strings.Contains(base, "..") {
		return "", fmt.Errorf("invalid fileName: contains path traversal")
	}
	if len(base) > 255 {
		return "", fmt.Errorf("fileName too long")
	}
	return base, nil
}

// SafeObjectKey 校验对象存储的 key（如 COS/MinIO objectName），禁止包含 ".." 等路径遍历
func SafeObjectKey(objectKey string) error {
	if objectKey == "" {
		return fmt.Errorf("object key cannot be empty")
	}
	if strings.Contains(objectKey, "..") {
		return fmt.Errorf("object key contains path traversal")
	}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Pass an actual file name, not a directory or dot path
2. Strip directory components client-side before sending only the base name

When it happens

Trigger: Thrown at internal/utils/security.go:136 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/40934789addadd8d. Report an issue: GitHub.