AlistGo/alist · error

failed to parse download_params: %w

Error message

failed to parse download_params: %w

What it means

The url_tree driver parses the optional download_params mount option as a Go text/template at Init time. If the string is not valid template syntax, template.New(...).Parse fails and Init aborts with this wrapped error, so the storage is never registered.

Source

Thrown at drivers/url_tree/driver.go:48

	return config
}

func (d *Urls) GetAddition() driver.Additional {
	return &d.Addition
}

func (d *Urls) Init(ctx context.Context) error {
	node, err := BuildTree(d.UrlStructure, d.HeadSize)
	if err != nil {
		return err
	}
	node.calSize()
	d.root = node
	d.downloadParamsTmpl = nil
	if params := strings.TrimSpace(d.DownloadParams); params != "" {
		tmpl, err := template.New("downloadParams").Parse(params)
		if err != nil {
			return fmt.Errorf("failed to parse download_params: %w", err)
		}
		d.downloadParamsTmpl = tmpl
	}
	return nil
}

func (d *Urls) Drop(ctx context.Context) error {
	return nil
}

func (d *Urls) Get(ctx context.Context, path string) (model.Obj, error) {
	d.mutex.RLock()
	defer d.mutex.RUnlock()
	node := GetNodeFromRootByPath(d.root, path)
	return nodeToObj(node, path)
}

func (d *Urls) List(ctx context.Context, dir model.Obj, args model.ListArgs) ([]model.Obj, error) {

View on GitHub (pinned to 843d9dc814)

Solutions

1. Fix the template syntax in download_params; valid magic variables are Name, Path, Size, Modified (e.g. "token=xxx&name={{.Name}}").
2. Validate the template locally with Go or an online text/template checker before saving the storage config.
3. Leave download_params empty if no extra query parameters are needed — empty is skipped entirely.

Example fix

// before (invalid: unclosed action)
download_params = "token=abc&file={{.Name"

// after
download_params = "token=abc&file={{.Name}}"

func validateDownloadParams(params string) error {
    if strings.TrimSpace(params) == "" { return nil }
    _, err := template.New("downloadParams").Parse(params)
    return err // surface before saving storage config
}

if err := storage.Init(ctx); err != nil && strings.Contains(err.Error(), "failed to parse download_params") {
    // show template syntax error to user editing the storage config
}

When it happens

Trigger: Configuring a url_tree storage whose download_params contains invalid template syntax — unclosed {{ , unknown functions, stray {{end}}, or unmatched delimiters.

Common situations: Copy-pasting a template with smart quotes, forgetting the pipe on {{.Name | urlquery}}, using a function that does not exist in text/template, or trailing '{{'. Fails at storage-add time, not at download time.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to render download_params: %w
• invalid download_params %q: %w
• the line '%s' is not a multiple of 2
• invalid line: %s, because url is required for file
• invalid line: %s, because file info must end with ':'

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