larksuite/cli · error · LarkCliError

--max-sheets must be at least 1

Error message

--max-sheets must be at least 1

What it means

prepareSuite inspects the staged suite archive by listing direct subdirectories under suitePath/references via listDirectSubdirs. If that read fails (directory missing or unreadable), the error is wrapped as 'inspect suite archive'. This happens before the archive's child-skill list is validated against the official skill names.

Source

Thrown at skills/lark-sheets/scripts/lark_inspect_workbook.py:88

    workbook = envelope_data(
        run_sheets(
            "+workbook-info",
            url=args.url,
            spreadsheet_token=args.spreadsheet_token,
            timeout=args.timeout,
        )
    )
    # An explicit selector must resolve: without require_one a typo'd
    # --sheet-id/--sheet-name silently yields sheet_count 0, which reads as
    # "empty workbook" instead of a locator error.
    target_sheets = resolve_target_sheets(
        workbook,
        sheet_id=args.sheet_id,
        sheet_name=args.sheet_name,
        require_one=bool(args.sheet_id or args.sheet_name),
    )
    if args.max_sheets < 1:
        raise LarkCliError("--max-sheets must be at least 1")
    inspect_count = len(target_sheets)
    if not args.sheet_id and not args.sheet_name:
        inspect_count = min(len(target_sheets), args.max_sheets)
        if inspect_count < len(target_sheets):
            warnings.append(
                f"layout and preview skipped for {len(target_sheets) - inspect_count} sheets; "
                f"pass --sheet-id or --sheet-name to inspect one"
            )

    profiles = []
    for position, sheet in enumerate(target_sheets):
        sid = sheet_identifier(sheet)
        title = sheet_title(sheet)
        profile = _sheet_summary(sheet)
        if position >= inspect_count:
            profiles.append(profile)
            continue
        locator = sheet_locator(sheet)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Inspect the wrapped cause to see whether references/ is missing vs unreadable, then check the staged path .agents/skills/lark-suite/references exists.
2. Verify the suite archive layout matches the expected .agents/skills/lark-suite structure; re-download a fresh archive.
3. Update the CLI if the upstream suite archive format changed (version mismatch between runner and archive layout).
4. Clear the staging/cache area and retry the sync to rule out a corrupt extraction.

Example fix

// before: suite archive missing references/ (old layout)
archive: {skills: {lark-suite: {SKILL.md}}}
// after: expected layout
archive: {.agents: {skills: {lark-suite: {SKILL.md, references: {auth/, docs/}}}}}

// Verify the expected suite layout before syncing
if _, err := os.Stat(filepath.Join(staging, ".agents", "skills", "lark-suite", "references")); err != nil {
    return fmt.Errorf("suite archive missing references/: %w", err)
}

func hasSuiteLayout(root string) bool {
    st, err := os.Stat(filepath.Join(root, ".agents", "skills", "lark-suite", "references"))
    return err == nil && st.IsDir()
}

if err := syncLayout(...); err != nil && strings.Contains(err.Error(), "inspect suite archive") {
    // staged tree lacks .agents/skills/lark-suite/references: re-download or upgrade CLI
}

When it happens

Trigger: A suite-mode skills sync where the staged archive does not contain the expected .agents/skills/lark-suite/references directory (wrong archive layout, empty/corrupt staging result, or a StageSuite implementation that unpacked to an unexpected path).

Common situations: Upstream suite archive format changed so references/ moved or was renamed; StageSuite silently succeeded but unpacked nothing due to a path mismatch; a mocked runner staging an incomplete tree in tests; corrupt archive extraction.

Related errors

• annotated_csv did not parse into the rows the server reporte
• +csv-get truncated the scan range at {actual_range}; narrow
• invalid chart size: {size!r}
• No visible worksheet matched
• %s: path must be absolute, got %q

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