nanocoai/nanoclaw · error · Error

--folder is required

Error message

--folder is required

What it means

Thrown by `ncl groups create` when no --folder argument is supplied. The folder is the canonical identifier for a group's on-disk workspace (groups/<folder>/), so the CLI refuses to mint one implicitly. Note there is an earlier template branch that does not require it — this throw only fires on the plain create path.

Source

Thrown at src/cli/resources/groups.ts:159

                  '. Pass --id <group-id> to update one, or --new to stamp another agent.',
              );
            }
            const targetId = args.id ? String(args.id) : carriers[0]?.id;
            if (targetId) {
              const result = await restampAgentFromTemplate(ref, targetId, { apply: args.yes === true });
              return result.applied
                ? result
                : { ...result, note: `${result.note} Pass --new to stamp a separate agent instead.` };
            }
          }
          const { group, report } = await createAgentFromTemplate(ref, {
            name: args.name ? String(args.name) : undefined,
            timezone,
          });
          return report.length > 0 ? { ...group, templateReport: report } : group;
        }
        const folder = args.folder as string;
        if (!folder) throw new Error('--folder is required');
        // The template path validates through createAgentFromTemplate; the bare
        // path used to validate nowhere, minting folders the runtime label
        // grammar refuses at every spawn.
        assertValidGroupFolder(folder);
        const name = (args.name as string) ?? folder;
        const existing = await getAgentGroupByFolder(folder);
        if (existing) {
          await initGroupFilesystem(existing); // ensure a reused group is fully configured too (idempotent; also repairs a missing workspace folder)
          return existing;
        }
        // Fresh-create branch only: a folder on disk with no claiming DB row
        // is deleted-group residue (delete never removes groups/<folder>/) or
        // an operator-placed dir — minting a new id over it would silently
        // re-scope the old group's data under a new identity.
        if (groupFolderExistsOnDisk(folder)) {
          throw new Error(
            `group folder 'groups/${folder}' already exists on disk but no agent group claims it — ` +
              `deleting a group never removes its folder, and creating a new group over it would silently ` +

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Add --folder <folder-name> to the command: `ncl groups create --folder my-agent --name "My Agent"`
2. If you intended to stamp a group from a template, use --template instead — that branch derives the folder
3. Check `ncl groups help` for the full flag list before scripting creates

Example fix

// before
ncl groups create --name "My Agent"
// after
ncl groups create --folder my-agent --name "My Agent"

// Before invoking: 
if (!opts.folder) throw new Error('groups create requires --folder on the non-template path');
const res = await execNcl(['groups','create','--folder',opts.folder, ...(opts.name?['--name',opts.name]:[])]);

const isCreateArgs = (a: {folder?: unknown; template?: unknown}): a is {folder: string; template?: string} =>
  typeof a.folder === 'string' && a.folder.length > 0;

try { await create(...) } catch (e) { if (e instanceof Error && e.message === '--folder is required') throw new UsageError('pass --folder'); throw e; }

When it happens

Trigger: Running `ncl groups create` (without --template) and omitting --folder, e.g. `ncl groups create --name my-agent`. The handler reads args.folder, finds it undefined, and throws before any DB or filesystem work.

Common situations: Operators copying a create command from memory/older docs that assumed --name alone was enough, or scripts that conditionally pass flags and skip --folder. Also hitting this after using the template flow (which doesn't need --folder) and expecting the same ergonomics from the bare create.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• --id is required
• ${def.name} id is required
• --${col.name.replace(/_/g, '-')} is required
• group folder 'groups/${folder}' already exists on disk but n
• group not found: ${id}

AI-assisted analysis of nanocoai/nanoclaw@294ef2aee8 (2026-08-28). Data as JSON: /api/errors/fddaccdc879cca7b. Report an issue: GitHub.