AlistGo/alist · error

%s: %v

Error message

%s: %v

What it means

Google Photo upload (Put) error: the upload-session init request (X-Goog-Upload-START style) returned a structured API error with non-zero code other than 401, formatted as '<message>: <errors>'. Google Photos is strictly quota-limited, so this is frequently an uploads quota or scope problem.

Source

Thrown at drivers/google_photo/driver.go:115

		"X-Goog-Upload-Raw-Size":     strconv.FormatInt(stream.GetSize(), 10),
	}
	url := "https://photoslibrary.googleapis.com/v1/uploads"
	res, err := base.NoRedirectClient.R().SetHeaders(postHeaders).
		SetError(&e).
		Post(url)

	if err != nil {
		return err
	}
	if e.Error.Code != 0 {
		if e.Error.Code == 401 {
			err = d.refreshToken()
			if err != nil {
				return err
			}
			return d.Put(ctx, dstDir, stream, up)
		}
		return fmt.Errorf("%s: %v", e.Error.Message, e.Error.Errors)
	}

	//Upload to the Google Photo
	postUrl := res.Header().Get("X-Goog-Upload-URL")
	//chunkSize := res.Header().Get("X-Goog-Upload-Chunk-Granularity")
	postHeaders = map[string]string{
		"X-Goog-Upload-Command": "upload, finalize",
		"X-Goog-Upload-Offset":  "0",
	}

	resp, err := d.request(postUrl, http.MethodPost, func(req *resty.Request) {
		req.SetBody(driver.NewLimitedUploadStream(ctx, stream)).SetContext(ctx)
	}, nil, postHeaders)

	if err != nil {
		return err
	}
	//Create MediaItem

View on GitHub (pinned to 843d9dc814)

Solutions

1. Enable the Google Photos Library API and request verification for restricted scopes in the Cloud project
2. Re-consent OAuth with the required upload scopes (photoslibrary.appendonly)
3. If quota reasons appear, pause uploads — Photos upload quotas reset daily and on a rolling window
4. Write to albums the credential owns or is explicitly granted write on

func isPhotosQuotaError(err error) bool {
  return err != nil && strings.Contains(err.Error(), "Quota") || strings.Contains(err.Error(), "libraryApiUpdatesDisabled")
}

err := d.Put(ctx, dstDir, stream, up)
if err != nil {
  if strings.Contains(err.Error(), "libraryApiUpdatesDisabled") { /* API access problem: fix project config */ return err }
  if strings.Contains(err.Error(), "Quota") { /* schedule retry after quota window resets */ }
}

When it happens

Trigger: Starting a media upload where init fails: libraryApiUpdatesDisabled (API access not enabled for the project), insufficient permissions (photoslibrary.appendonly scope missing), album quota exceeded, or malformed upload metadata.

Common situations: Google Photos API library not enabled in the Cloud project; OAuth token granted without the appendonly/uploads scope; hitting the 25,000-item or requests-per-minute limits; album is a shared album the token cannot write to.

Related errors

• %s: %v
• %s: %v
• 123 offline download cannot target the root directory, pick
• instant upload returns empty task id
• upload token is incomplete

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