AlistGo/alist · error

resolve offline resource failed: %s

Error message

resolve offline resource failed: %s

What it means

ResolveOfflineResource POSTs the user-supplied URL to /cloudcollection/v1/resolve_res and throws when the envelope Msg is not 'success'. Resolution is the provider's URL analysis step (magnet/HTTP link inspection) before an offline task can be created; failure means the provider could not or would not analyze the link.

Source

Thrown at drivers/guangyapan/offline.go:30

)

func (d *GuangYaPan) ResolveOfflineResource(ctx context.Context, fileURL string) (*OfflineResolveData, error) {
	if err := d.ensureAccessToken(ctx); err != nil {
		return nil, err
	}
	fileURL = strings.TrimSpace(fileURL)
	if fileURL == "" {
		return nil, errors.New("offline url is empty")
	}

	var resp offlineResolveResp
	if err := d.postAPI(ctx, "/cloudcollection/v1/resolve_res", map[string]any{
		"url": fileURL,
	}, &resp); err != nil {
		return nil, err
	}
	if !isSuccessMsg(resp.Msg) {
		return nil, fmt.Errorf("resolve offline resource failed: %s", strings.TrimSpace(resp.Msg))
	}
	return &resp.Data, nil
}

func (d *GuangYaPan) OfflineDownload(ctx context.Context, fileURL string, parentDir model.Obj, fileName string) (*OfflineTask, error) {
	resolved, err := d.ResolveOfflineResource(ctx, fileURL)
	if err != nil {
		return nil, err
	}

	parentID := parentDir.GetID()
	rootID, err := d.getRootFolderID(ctx)
	if err != nil {
		return nil, err
	}
	if parentID == rootID {
		parentID = ""
	}

View on GitHub (pinned to 843d9dc814)

Solutions

1. Test the URL in a browser/downloader to confirm it is reachable and public.
2. Use a different mirror or a healthy magnet for the same content.
3. Retry later if the provider's offline service is flaky.

// validate the link before calling OfflineDownload
u := strings.TrimSpace(fileURL)
if u == "" { return errors.New("empty offline url") }
if !strings.HasPrefix(u, "http://") && !strings.HasPrefix(u, "https://") && !strings.HasPrefix(u, "magnet:") {
    return fmt.Errorf("unsupported offline url scheme: %q", u)
}

if _, err := d.OfflineDownload(ctx, fileURL, parentDir, fileName); err != nil {
    if strings.Contains(err.Error(), "resolve offline resource failed") {
        // link itself is bad: do not retry; ask user for a valid URL
        return fmt.Errorf("link could not be resolved (dead/unsupported/private): %w", err)
    }
    return err
}

When it happens

Trigger: OfflineDownload called with a dead 404 link, unsupported protocol, malformed magnet URI, geo-blocked or auth-walled URL, or when the resolver service is down.

Common situations: Magnet links with no seeders that fail analysis; URLs requiring login (private buckets); provider suspended the resolve service; link pasted with surrounding whitespace/quotes (though basic trim happens).

Related errors

• offline url is empty
• create offline task failed: empty task id
• GuangYaPan offline download only supports GuangYaPan destina
• failed
• canceled

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/02923298048c078c. Report an issue: GitHub.