Tencent/WeKnora · error

invalid resource reference

Error message

invalid resource reference

What it means

Resolve validates the incoming reference string through types.ParseResourcePath before doing any repo lookup. A reference that is not a well-formed catalog resource path (e.g. a raw provider path or arbitrary string) is rejected with this error. It is an input-validation error, thrown before any database access.

Source

Thrown at internal/application/service/resource.go:115

			Lifecycle:        lifecycle,
		}
		if err := s.repo.Create(ctx, resource); err == nil {
			return types.BuildResourcePath(handle), nil
		} else if !strings.Contains(strings.ToLower(err.Error()), "unique") {
			return "", err
		}
		existing, lookupErr := s.repo.GetByTenantLocation(ctx, tenantID, locationHash)
		if lookupErr == nil && existing != nil {
			return types.BuildResourcePath(existing.Handle), nil
		}
	}
	return "", fmt.Errorf("failed to allocate unique resource handle")
}

func (s *resourceCatalog) Resolve(ctx context.Context, reference string) (*types.StoredResource, error) {
	handle, ok := types.ParseResourcePath(reference)
	if !ok {
		return nil, fmt.Errorf("invalid resource reference")
	}
	resource, err := s.repo.GetByHandle(ctx, handle)
	if err != nil {
		return nil, err
	}
	if resource == nil {
		return nil, fmt.Errorf("resource not found")
	}
	return resource, nil
}

func (s *resourceCatalog) ResolvePath(ctx context.Context, value string) (string, *types.StoredResource, error) {
	if _, ok := types.ParseResourcePath(value); !ok {
		return value, nil, nil
	}
	resource, err := s.Resolve(ctx, value)
	if err != nil {
		return "", nil, err

View on GitHub (pinned to 988cbb0330)

Solutions

1. Use the value returned from Register (types.BuildResourcePath output) rather than a raw storage path
2. Run types.ParseResourcePath on the reference before the call to fail fast
3. For legacy raw paths, route through the Register/lookup flow to obtain a valid handle
4. Check for encoding/truncation when persisting or passing references between services

Example fix

// before
res, err := catalog.Resolve(ctx, "s3://bucket/obj")
// after
handle, ok := types.ParseResourcePath("s3://bucket/obj")
if !ok {
    return fmt.Errorf("not a catalog reference")
}
res, err := catalog.Resolve(ctx, types.BuildResourcePath(handle))

if _, ok := types.ParseResourcePath(reference); !ok { return fmt.Errorf("invalid reference: %q", reference) }

func isResourceReference(s string) bool { _, ok := types.ParseResourcePath(s); return ok }

res, err := catalog.Resolve(ctx, ref)
if err != nil && strings.Contains(err.Error(), "invalid resource reference") {
    return fmt.Errorf("%w: %q", ErrBadReference, ref)
}

When it happens

Trigger: Passing a raw provider file path, empty string, or any string lacking the catalog handle format to Resolve (directly or via ResolvePath, Bind, Release, MarkDeleted, CreateAccessGrant).

Common situations: Storing/transporting raw storage paths instead of the resource:// style handle; legacy code paths that predate the catalog; trimming/serialization corrupting the reference.

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/1819c464df325379. Report an issue: GitHub.