AlistGo/alist · error

sub_id is required when exporting lark type %q as %q

Error message

sub_id is required when exporting lark type %q as %q

What it means

Validation error in the Lark driver's createExportTask: larkExportFormatRequiresSubID returns true for a docType/format combination (a secondary sub-document must be identified) but the request's SubID field is empty after trimming. Lark's export API requires a sub_id for those combinations to know which sub-sheet/sub-document to export.

Source

Thrown at drivers/lark/other.go:126

	return nil
}

func (c *Lark) createExportTask(ctx context.Context, obj model.Obj, req larkExportCreateReq) (*LarkExportCreateResp, error) {
	token, ok := c.getObjToken(ctx, obj.GetPath())
	if !ok {
		return nil, errors.WithStack(errors.New("lark file token not found"))
	}
	docType, err := larkExportType(obj.GetName())
	if err != nil {
		return nil, err
	}
	format := strings.ToLower(strings.TrimSpace(req.Format))
	if !larkExportFormatAllowed(docType, format) {
		return nil, fmt.Errorf("unsupported export format %q for lark type %q", format, docType)
	}
	subID := strings.TrimSpace(req.SubID)
	if larkExportFormatRequiresSubID(docType, format) && subID == "" {
		return nil, fmt.Errorf("sub_id is required when exporting lark type %q as %q", docType, format)
	}

	builder := larkdrive.NewExportTaskBuilder().
		Token(token).
		Type(docType).
		FileExtension(format).
		FileName(larkExportBaseName(obj.GetName()))
	if subID != "" {
		builder.SubId(subID)
	}
	exportTask := builder.Build()
	resp, err := doDrive(ctx, c, func(opts ...larkcore.RequestOptionFunc) (*larkdrive.CreateExportTaskResp, error) {
		return c.client.Drive.V1.ExportTask.Create(ctx,
			larkdrive.NewCreateExportTaskReqBuilder().ExportTask(exportTask).Build(), opts...)
	})
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 843d9dc814)

Solutions

1. Populate req.SubID with the id of the sub-document/sub-sheet to export (trimmed of whitespace).
2. List the object's children/sub-documents first to obtain valid sub ids before creating the task.
3. If you did not intend a sub-id-requiring format, switch the format to one that does not require it (e.g. pdf/docx for docs).
4. Update OpenList — the sub-id requirement matrix may have been refined upstream.

Example fix

// before
req := larkExportCreateReq{Format: "csv"} // needs SubID -> error
// after
req := larkExportCreateReq{Format: "csv", SubID: "sheetId_abc123"}

if larkExportFormatRequiresSubID(docType, format) && strings.TrimSpace(req.SubID) == "" {
    return errors.New("fill SubID before creating this export task")
}
// enumerate sub-documents first to obtain ids

if err != nil && strings.Contains(err.Error(), "sub_id is required") {
    // fetch sub-document list, populate SubID, retry once
}

When it happens

Trigger: Creating an export task for a format flagged as requiring a sub-document id (per the internal format/subID matrix) while omitting req.SubID or sending only whitespace.

Common situations: Callers reuse a create request built for a simple doc and forget the sub-document selector when exporting sheets/bitable; frontend forms that do not expose a sub-id field; copying an example payload that lacks sub_id.

Related errors

• unsupported export format %q for lark type %q
• unsupported lark export file type: %s
• ticket is required
• lark file token not found
• lark export task response missing ticket

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