larksuite/cli · error

writing sheet %q failed: %w

Error message

writing sheet %q failed: %w

What it means

After a payload sheet is matched or created, writeTypedSheets calls writeSheetData to write its rows. This error wraps any failure inside that write (append-anchor resolution, batch writes, or style application), tagged with the sheet name. It is returned with sheets written so far and surfaced as a partial_success message string via tablePutPartial.

Source

Thrown at shortcuts/sheets/lark_sheet_table_io.go:1070

			// 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 {
	_, err := callTool(ctx, runtime, token, ToolKindWrite, "modify_workbook_structure", map[string]interface{}{
		"excel_id":  token,
		"operation": "rename",
		"sheet_id":  sheetID,
		"new_name":  newName,
	})
	return err
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Read the partial_success message: it names the failing sheet; earlier sheets were written successfully.
2. Re-run the put for just the failing sheet after fixing the underlying cause (mode, grid size, permissions).
3. If the write collided with existing data, switch to overwrite mode or clear the target range first.
4. Retry on transient/rate-limit errors with backoff.

Example fix

// before: one sheet too large for created grid
{"sheets": [{"name": "A", "rows": 1000-row-array}]}
// after: write in chunks per sheet, or specify explicit grid size so creation matches the payload

if strings.Contains(err.Error(), "writing sheet") {
	// extract sheet name and underlying cause; fix cause, re-put only that sheet
}

When it happens

Trigger: lark sheet table put where the per-sheet write fails for any reason — lastDataRow resolution failure, set_cell_range batch rejection (collision/allow_overwrite, too-small grid), or visual style application failure.

Common situations: Multi-sheet payloads where one sheet's data doesn't fit its grid; overwrite collisions; transient API failures partway through a large multi-sheet write.

Related errors

• writing rows %d-%d: %w
• applying visual styles: %w
• creating sheet %q failed: %w
• +csv-get truncated the requested range at {source_range}; na
• Invalid column: {col}

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