What causes "sheet %q created but resolving its id failed: %w" in larksuite/cli?

Re-run the put; the second attempt will likely find the already-created sheet by name instead of creating a duplicate.

sheet %q created but resolving its id failed: %w

Error message

sheet %q created but resolving its id failed: %w

What it means

createSheet issues the modify_workbook_structure create call, then looks up the new sheet's ID by name via lookupSheetIndex. This error means the sheet was created but the follow-up ID lookup failed, leaving the write unable to proceed. It is surfaced as a partial_success message string via tablePutPartial.

Source

Thrown at shortcuts/sheets/lark_sheet_table_io.go:1132

// across tool-response variations.
func createSheet(ctx context.Context, runtime *common.RuntimeContext, token, name string, rows, cols int) (string, error) {
	input := map[string]interface{}{
		"excel_id":   token,
		"operation":  "create",
		"sheet_name": name,
	}
	if rows > 0 {
		input["rows"] = rows
	}
	if cols > 0 {
		input["columns"] = cols
	}
	if _, err := callTool(ctx, runtime, token, ToolKindWrite, "modify_workbook_structure", input); err != nil {
		return "", err
	}
	id, _, err := lookupSheetIndex(ctx, runtime, token, "", name)
	if err != nil {
		return "", fmt.Errorf("sheet %q created but resolving its id failed: %w", name, err) //nolint:forbidigo // intermediate error; surfaced as a partial_success message string via tablePutPartial, not a typed final error
	}
	return id, nil
}

// sheetCreateDims sizes a to-be-created sheet to the spec's write range so the
// grid matches the payload from the start (the backend would also auto-expand
// on write; see createSheet). It accounts for the start_cell offset, the
// optional header row, and any --styles extent (so a cell_styles / merge /
// resize op past the data still fits the grid). The backend's 20×200 defaults
// are kept as floors (ordinary small tables are created exactly as before) and
// its hard limits (200 cols, 50000 rows) as ceilings.
func sheetCreateDims(s *tableSheetSpec, styles *workbookCreateStylePayload) (rows, cols int) {
	_, col0, row0, _ := sheetAnchor(s)
	cols = col0 + len(s.Columns)
	rows = row0 + len(s.Rows)
	// Match writeSheetData's header decision exactly. headerOn() is false for
	// append mode by default, but writeSheetData *forces* a header when append
	// hits an empty sheet with no explicit Header choice (so column names

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Re-run the put; the second attempt will likely find the already-created sheet by name instead of creating a duplicate.
Check for a duplicate sheet left by the failed run and remove it if the retry hits a name conflict.
Back off and retry if the cause is rate limiting after the structure mutation.
Verify listing permissions on the workbook if lookups consistently fail.

Example fix

// before: retry immediately (may duplicate or conflict)
lark sheet table put --token T --sheet Metrics ...
// after: list sheets first, then retry only if missing
lark sheet table get --token T --sheet Metrics || lark sheet table put --token T --sheet Metrics ...

Defensive patterns

Strategy: retry

Validate before calling

// after any create, confirm the sheet resolves before writing:
out, err := runCLI("lark", "sheet", "table", "get", "--token", token, "--sheet", name)
if err != nil { /* sheet missing or unreadable — clean up or retry */ }

Try / catch

if strings.Contains(err.Error(), "created but resolving its id failed") {
	// list sheets; if it exists, retry the put (it will match by name)
}

Prevention

Back off after structure mutations before follow-up calls.
Check for duplicate sheets left by failed runs.
Keep workbooks modest in sheet count to avoid slow listings.

When it happens

Trigger: lark sheet table put creating a new sheet where the create succeeds but the immediate sheet-list/lookup fails — transient API error, rate limit, or the listing call rejects due to permissions.

Common situations: Rate limiting right after a structure mutation; flaky network between the two calls; very large workbooks where listing times out.

Related errors

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