larksuite/cli · error

creating sheet %q failed: %w

Error message

creating sheet %q failed: %w

What it means

When a payload sheet name does not match any existing sheet in the workbook, writeTypedSheets creates it with the exact grid size the payload needs. This error wraps a createSheet failure and is returned with the list of sheets written so far, then surfaced as a partial_success message string via tablePutPartial.

Source

Thrown at shortcuts/sheets/lark_sheet_table_io.go:1062

	written := make([]interface{}, 0, len(payload.Sheets))
	for i := range payload.Sheets {
		s := &payload.Sheets[i]
		sheetID, ok := byName[s.Name]
		if !ok {
			// The missing target will be created EMPTY, so append resolves its
			// base row to the static anchor — validate style anchors (row
			// included) BEFORE the create. Validate could not run this check
			// for append (an existing sheet's base row is dynamic), and
			// skipping it here would strand a freshly created empty sheet
			// behind a "no sheets were written" failure.
			if err := checkSheetStyleAnchors(s, styles.styleFor(i), true); err != nil {
				return written, err
			}
			rows, cols := sheetCreateDims(s, styles.styleFor(i))
			sheetID, err = createSheet(ctx, runtime, token, s.Name, rows, cols)
			if err != nil {
				return written, fmt.Errorf("creating sheet %q failed: %w", s.Name, err) //nolint:forbidigo // intermediate error; surfaced as a partial_success message string via tablePutPartial, not a typed final error
			}
			byName[s.Name] = sheetID
			// A freshly created sheet's grid is exactly what we just asked for.
			dimsByName[s.Name] = gridDims{rows: rows, cols: cols}
		}
		summary, err := writeSheetData(ctx, runtime, token, sheetID, s, styles.styleFor(i), dimsByName[s.Name])
		if err != nil {
			return written, fmt.Errorf("writing sheet %q failed: %w", s.Name, err) //nolint:forbidigo // intermediate error; surfaced as a partial_success message string via tablePutPartial, not a typed final error
		}
		written = append(written, summary)
	}
	return written, nil
}

// renameSheet renames a sub-sheet in place via modify_workbook_structure. Used
// to adopt a freshly created workbook's default sheet as the first typed sheet
// (see writeTypedSheets); mirrors +sheet-rename's tool input.
func renameSheet(ctx context.Context, runtime *common.RuntimeContext, token, sheetID, newName string) error {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Check partial_success: sheets before the failing one were written; retry the whole put or target only the missing sheet.
2. Ensure the sheet name doesn't already exist (or reuse it by matching the existing name).
3. Use a simpler ASCII sheet title without slashes or special characters.
4. Confirm the token has permission to modify workbook structure.

Example fix

// before: concurrent duplicate creation
lark sheet table put --token T --sheet Sales --row ... &  lark sheet table put --token T --sheet Sales --row ...
// after: serialize the puts or put into distinct sheet names

// ensure no concurrent creator and a valid unique name:
if existingNames[sheetName] { return fmt.Errorf("sheet %q already exists", sheetName) }

if strings.Contains(err.Error(), "creating sheet") {
	// note sheets already written from partial_success; retry only the missing sheet
}

When it happens

Trigger: lark sheet table put with a new sheet name where the modify_workbook_structure create call fails: duplicate name race (another sheet just created with that name), invalid sheet title, permission denial, or API error.

Common situations: Two concurrent puts creating the same sheet name; sheet titles with characters the API rejects; token without structure-edit rights; rate limiting on workbooks with many sheets.

Related errors

• writing rows %d-%d: %w
• applying visual styles: %w
• writing sheet %q failed: %w
• sheet %q created but resolving its id failed: %w
• +csv-get truncated the requested range at {source_range}; na

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