{"record":{"id":"fddaccdc879cca7b","repo":"nanocoai/nanoclaw","slug":"folder-is-required","errorCode":null,"errorMessage":"--folder is required","messagePattern":"--folder is required","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/cli/resources/groups.ts","lineNumber":159,"sourceCode":"                  '. Pass --id <group-id> to update one, or --new to stamp another agent.',\n              );\n            }\n            const targetId = args.id ? String(args.id) : carriers[0]?.id;\n            if (targetId) {\n              const result = await restampAgentFromTemplate(ref, targetId, { apply: args.yes === true });\n              return result.applied\n                ? result\n                : { ...result, note: `${result.note} Pass --new to stamp a separate agent instead.` };\n            }\n          }\n          const { group, report } = await createAgentFromTemplate(ref, {\n            name: args.name ? String(args.name) : undefined,\n            timezone,\n          });\n          return report.length > 0 ? { ...group, templateReport: report } : group;\n        }\n        const folder = args.folder as string;\n        if (!folder) throw new Error('--folder is required');\n        // The template path validates through createAgentFromTemplate; the bare\n        // path used to validate nowhere, minting folders the runtime label\n        // grammar refuses at every spawn.\n        assertValidGroupFolder(folder);\n        const name = (args.name as string) ?? folder;\n        const existing = await getAgentGroupByFolder(folder);\n        if (existing) {\n          await initGroupFilesystem(existing); // ensure a reused group is fully configured too (idempotent; also repairs a missing workspace folder)\n          return existing;\n        }\n        // Fresh-create branch only: a folder on disk with no claiming DB row\n        // is deleted-group residue (delete never removes groups/<folder>/) or\n        // an operator-placed dir — minting a new id over it would silently\n        // re-scope the old group's data under a new identity.\n        if (groupFolderExistsOnDisk(folder)) {\n          throw new Error(\n            `group folder 'groups/${folder}' already exists on disk but no agent group claims it — ` +\n              `deleting a group never removes its folder, and creating a new group over it would silently ` +","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/nanocoai/nanoclaw/blob/294ef2aee85218b23ad30eda9dfe10e590b54a8c/src/cli/resources/groups.ts#L141-L177","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add --folder <folder-name> to the command: `ncl groups create --folder my-agent --name \"My Agent\"`","If you intended to stamp a group from a template, use --template instead — that branch derives the folder","Check `ncl groups help` for the full flag list before scripting creates"],"exampleFix":"// before\nncl groups create --name \"My Agent\"\n// after\nncl groups create --folder my-agent --name \"My Agent\"","handlingStrategy":"validation","validationCode":"// Before invoking: \nif (!opts.folder) throw new Error('groups create requires --folder on the non-template path');\nconst res = await execNcl(['groups','create','--folder',opts.folder, ...(opts.name?['--name',opts.name]:[])]);","typeGuard":"const isCreateArgs = (a: {folder?: unknown; template?: unknown}): a is {folder: string; template?: string} =>\n  typeof a.folder === 'string' && a.folder.length > 0;","tryCatchPattern":"try { await create(...) } catch (e) { if (e instanceof Error && e.message === '--folder is required') throw new UsageError('pass --folder'); throw e; }","preventionTips":["Always pass --folder explicitly in scripts rather than relying on defaults","Use the --template branch only when you actually want template-derived folders"],"tags":["cli","missing-argument","groups"],"backgroundTag":"missing-required-argument","analyzedSha":"294ef2aee85218b23ad30eda9dfe10e590b54a8c","analyzedAt":"2026-08-28T13:59:10.357Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}