AlistGo/alist · warning

offline url is empty

Error message

offline url is empty

What it means

ResolveOfflineResource trims the incoming fileURL and rejects an empty string before calling POST /cloudcollection/v1/resolve_res. It is a pure input-validation error: the offline-download resolver has nothing to resolve. All later API work (auth, rate limit, resolve call) is skipped.

Source

Thrown at drivers/guangyapan/offline.go:20

import (
	"context"
	"errors"
	"fmt"
	"net/url"
	stdpath "path"
	"strings"

	"github.com/alist-org/alist/v3/internal/model"
)

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

View on GitHub (pinned to 843d9dc814)

Solutions

1. Validate the URL client-side before creating the offline task (required field, non-blank)
2. In calling code, skip/filter empty entries when batch-creating offline tasks
3. URL-encode the value after trimming to avoid whitespace-only strings slipping through

Example fix

// before
resolve, err := d.ResolveOfflineResource(ctx, taskURL)
// after
if strings.TrimSpace(taskURL) == "" {
	return errors.New("offline task url must not be empty")
}
resolve, err := d.ResolveOfflineResource(ctx, taskURL)

url := strings.TrimSpace(fileURL)
if url == "" {
	return nil, errors.New("offline download URL is required")
}
if !strings.Contains(url, "://") {
	return nil, fmt.Errorf("offline download URL looks invalid: %q", url)
}

When it happens

Trigger: ResolveOfflineResource called with "", " ", or a URL consisting only of whitespace. Typically the value came straight from user input in an offline-download task form.

Common situations: Frontend submitted an empty URL field; task-creation pipeline passed an unmarshalled JSON field that was absent; automation script iterated over a list with blank entries.

Related errors

• dir name is empty
• file id is empty
• new name is empty
• create offline task failed: empty task id
• login failed: provide a valid access_token, or refresh_token

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