Tencent/WeKnora · error

invalid OSS file path: %s

Error message

invalid OSS file path: %s

What it means

parseOssFilePath validates that a file reference uses the OSS URI scheme oss://{bucket}/{objectKey} before extracting bucket and key. This error is returned when the string does not start with the 'oss://' prefix, so no bucket/key can be parsed. It indicates the caller passed a raw path, URL, or incorrectly constructed identifier instead of a proper OSS URI.

Source

Thrown at internal/application/service/file/oss.go:139

	client, err := newOSSClient(endpoint, region, accessKey, secretKey)
	if err != nil {
		return err
	}

	exists, err := client.IsBucketExist(ctx, bucketName)
	if err != nil {
		return fmt.Errorf("failed to check OSS bucket: %w", err)
	}
	if !exists {
		return fmt.Errorf("bucket %q does not exist or is not accessible", bucketName)
	}
	return nil
}

// parseOssFilePath extracts bucket and object key from: oss://{bucket}/{objectKey}
func parseOssFilePath(filePath string) (bucketName string, objectKey string, err error) {
	if !strings.HasPrefix(filePath, ossScheme) {
		return "", "", fmt.Errorf("invalid OSS file path: %s", filePath)
	}

	rest := strings.TrimPrefix(filePath, ossScheme)
	parts := strings.SplitN(rest, "/", 2)
	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
		return "", "", fmt.Errorf("invalid OSS file path: %s", filePath)
	}
	return parts[0], parts[1], nil
}

// CheckConnectivity verifies OSS is reachable and the main bucket exists.
func (s *ossFileService) CheckConnectivity(ctx context.Context) error {
	checkCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
	defer cancel()

	exists, err := s.client.IsBucketExist(checkCtx, s.bucketName)
	if err != nil {
		return fmt.Errorf("failed to check OSS bucket: %w", err)

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the exact filePath value in the error message and ensure it starts with 'oss://'
2. Normalize stored references: if you have a bare key, wrap it as fmt.Sprintf("oss://%s/%s", bucket, key)
3. Migrate legacy DB rows to the oss:// scheme, or add a migration shim that prefixes missing schemes before calling the service
4. Reject/fix user input at the API boundary by validating the oss:// prefix before invoking the service

Example fix

// before
svc.GetFile(ctx, "my-knowledge/file.pdf")
// after
svc.GetFile(ctx, fmt.Sprintf("oss://%s/%s", bucketName, "my-knowledge/file.pdf"))

func isValidOssPath(p string) bool {
    rest, ok := strings.CutPrefix(p, "oss://")
    if !ok { return false }
    bucket, key, found := strings.Cut(rest, "/")
    return found && bucket != "" && key != ""
}
if !isValidOssPath(filePath) { return fmt.Errorf("invalid OSS path: %q", filePath) }

func isOssPath(s string) bool { return strings.HasPrefix(s, "oss://") }

bucket, key, err := parseOssFilePath(filePath)
if err != nil {
    return fmt.Errorf("cannot resolve file %q: %w", filePath, err)
}

When it happens

Trigger: Calling CopyFile, GetFile, DeleteFile, or GetFileURL with a path that lacks the oss:// prefix, e.g. 'mybucket/dir/file.txt', '/local/path/file.txt', 'https://bucket.oss-cn.aliyuncs.com/key', or an empty string.

Common situations: Storing bare object keys or full HTTP URLs in the database instead of OSS URIs; legacy records created before the oss:// scheme was adopted; user-supplied file references not normalized; constructing the path with the wrong constant prefix.

Related errors

• member_limit must be >= 0
• missing query parameter
• no queries provided
• missing id parameter
• knowledge_base_ids is required

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