AlistGo/alist · error
failed to parse download_params
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.
Solutions
- Fix the template syntax in download_params; valid magic variables are Name, Path, Size, Modified (e.g. "token=xxx&name={{.Name}}").
- Validate the template locally with Go or an online text/template checker before saving the storage config.
- 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}}" Defensive patterns
Strategy: validation
Validate before calling
func validateDownloadParams(params string) error {
if strings.TrimSpace(params) == "" { return nil }
_, err := template.New("downloadParams").Parse(params)
return err // surface before saving storage config
} Try / catch
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
} Prevention
- Dry-run template.New(...).Parse in a config lint step
- Use only text/template built-ins and the four magic variables
- Keep templates one-line and simple
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
- invalid download_params
- invalid line: , because file info must end with
- invalid line: , because file name can't be empty
- invalid line: , because file size must be an integer
AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15).
Data as JSON: /api/errors/a66ce098d70fe313.
Report an issue: GitHub.
Appendix: 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)