larksuite/cli · error

adopting the default sheet as %q failed: %w

Error message

adopting the default sheet as %q failed: %w

What it means

When a new workbook is created, table put tries to adopt its empty default sheet by renaming it to the first payload sheet's name instead of leaving a stray empty sheet. This error wraps a renameSheet failure during that adoption. It is surfaced as a partial_success message string via tablePutPartial; the workbook exists but its sheets may be partially set up.

Source

Thrown at shortcuts/sheets/lark_sheet_table_io.go:1023

// writes into an existing workbook, with no default sheet to adopt);
// +workbook-create passes the default sheet's id.
//
// On failure it returns the summaries written so far alongside the error, so
// the caller can surface a partial_success.
func writeTypedSheets(ctx context.Context, runtime *common.RuntimeContext, token string, payload *tablePayload, adoptSheetID string, styles *workbookCreateSheetStyles) ([]interface{}, error) {
	byName, dimsByName, err := listSheetIDsByName(ctx, runtime, token)
	if err != nil {
		return nil, err
	}

	// Adopt the default sheet as the first payload sheet (rename + reuse), so a
	// just-created workbook doesn't keep its empty default sheet around. Skip if
	// a sheet by that name already exists (it'll be matched normally below).
	if adoptSheetID != "" && len(payload.Sheets) > 0 {
		first := payload.Sheets[0].Name
		if _, exists := byName[first]; !exists {
			if err := renameSheet(ctx, runtime, token, adoptSheetID, first); err != nil {
				return nil, fmt.Errorf("adopting the default sheet as %q failed: %w", first, err) //nolint:forbidigo // intermediate error; surfaced as a partial_success message string via tablePutPartial, not a typed final error
			}
			// The adopted sheet's OLD name must stop resolving: a later payload
			// sheet named "Sheet1" would otherwise match the stale entry and
			// silently overwrite the first sheet's data (live-verified: a
			// [Sales, Sheet1] payload wrote both into one sheet, destroying
			// Sales, while reporting both as written). Its grid dims move to
			// the new name so append-mode's lastDataRow probe keeps its
			// full-grid anchor.
			for name, id := range byName {
				if id == adoptSheetID && name != first {
					delete(byName, name)
					if d, ok := dimsByName[name]; ok {
						dimsByName[first] = d
						delete(dimsByName, name)
					}
				}
			}
			byName[first] = adoptSheetID

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Retry the table put; a fresh workbook creation plus rename is usually idempotent-safe on retry.
2. Simplify the first sheet's name (ASCII, shorter, no special characters) and retry.
3. Verify the credential can modify workbooks in the target folder/domain.
4. Use an existing spreadsheet token instead of creating a new one to skip the adoption path.

Example fix

// before: name that trips backend constraints
{"sheets": [{"name": "Q4 / P&L (final)!!", "rows": [["a"]]}"]}
// after
{"sheets": [{"name": "Q4 PnL Final", "rows": [["a"]]}]}

// pre-validate the first sheet name for backend constraints:
if len(firstSheetName) == 0 || len(firstSheetName) > 100 || strings.ContainsAny(firstSheetName, "/\\?*[ ]:") {
	return fmt.Errorf("sheet name %q may be rejected", firstSheetName)
}

if strings.Contains(err.Error(), "adopting the default sheet") {
	// inspect workbook state (which sheets exist) before retrying the put
}

When it happens

Trigger: Creating a brand-new workbook via table put where the rename of the default sheet (e.g. 'Sheet1') to the first payload sheet name fails — typically a permission/API rejection on modify_workbook_structure, or a name constraint violation.

Common situations: Token lacking write permission on the just-created workbook; sheet name colliding with backend constraints (length, forbidden characters); transient API failure right after workbook creation.

Related errors

• +csv-get truncated the requested range at {source_range}; na
• Invalid column: {col}
• Column index must be >= 1: {index}
• Range needs a maximum column: {range_ref}
• Range needs a maximum row: {range_ref}

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/cc1b89e829ebe0c3. Report an issue: GitHub.