Tencent/WeKnora · error

register stored resource: %w

Error message

register stored resource: %w

What it means

resourceCatalogFileService wraps the storage service; after the inner service physically stores a file (SaveFile/SaveBytes/CopyFile), it calls s.catalog to register metadata. If registration fails, it compensates by deleting the physical file and returns this error. The stored data is rolled back; nothing persists.

Source

Thrown at internal/application/service/file/resource_catalog.go:82

	physical string,
	tenantID uint64,
	name string,
	size int64,
	temporary bool,
	contentHash string,
) (string, error) {
	kind, mimeType := resourceKind(name)
	ref, err := s.catalog.Register(ctx, tenantID, physical, interfaces.ResourceRegistration{
		Kind:         kind,
		MimeType:     mimeType,
		OriginalName: filepath.Base(name),
		Size:         size,
		ContentHash:  contentHash,
		Temporary:    temporary,
	})
	if err != nil {
		_ = s.inner.DeleteFile(ctx, physical)
		return "", fmt.Errorf("register stored resource: %w", err)
	}
	return ref, nil
}

func (s *resourceCatalogFileService) SaveFile(
	ctx context.Context,
	file *multipart.FileHeader,
	tenantID uint64,
	knowledgeID string,
) (string, error) {
	physical, err := s.inner.SaveFile(ctx, file, tenantID, knowledgeID)
	if err != nil {
		return "", err
	}
	ref, err := s.register(ctx, physical, tenantID, file.Filename, file.Size, false, "")
	if err != nil {
		return "", err
	}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped error to find the catalog (DB) root cause
2. Retry the Save operation — the failed physical object was already deleted, so no orphan
3. Check catalog table constraints/schema match what register writes (hash, size, temporary flags)
4. Ensure catalog DB connectivity and pool limits before bulk uploads

if err := catalog.HealthCheck(ctx); err != nil { return fmt.Errorf("catalog unavailable: %w", err) }

ref, err := svc.SaveFile(ctx, r, knowledgeID)
if err != nil && strings.Contains(err.Error(), "register stored resource") {
    time.Sleep(backoff)
    ref, err = svc.SaveFile(ctx, r, knowledgeID) // safe: physical object was rolled back
}

When it happens

Trigger: Catalog write failure (DB down, constraint violation, duplicate content-hash/ref, oversized metadata) right after the inner file service successfully stored the object.

Common situations: Database connection pool exhaustion or timeouts under load, unique constraint violations on content hash or resource ID, catalog migrations out of sync, transient network blips between object store and DB.

Related errors

• bind stored resource: %w
• failed to write file: %w
• failed to delete file from OSS: %w
• bind copied resource: %w
• failed to get file from S3: %w

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