windmill-labs/windmill · error · Error

Failed to create folder ${name}: ${e.body ?? e.message}

Error message

Failed to create folder ${name}: ${e.body ?? e.message}

What it means

Raised by pushFolder in the wmill CLI when creating a folder via the Windmill API fails. The CLI catches the API error and rethrows it with the folder name and the API error body or message attached, indicating the folder could not be created on the server during `wmill folder push`.

Source

Thrown at cli/src/commands/folder/folder.ts:148

      });
    } catch (e) {
      //@ts-ignore
      console.error(e.body);
      throw e;
    }
  } else {
    console.log(colors.bold.yellow("Creating new folder: " + name));
    try {
      await wmill.createFolder({
        workspace: workspace,
        requestBody: {
          name: name,
          ...localFolder,
        },
      });
    } catch (e) {
      //@ts-ignore
      throw Error(`Failed to create folder ${name}: ${e.body ?? e.message}`);
    }
  }
}

async function push(opts: GlobalOptions, name: string) {
  const workspace = await resolveWorkspace(opts);
  await requireLogin(opts);

  const metaPath = `f${SEP}${name}${SEP}folder.meta.yaml`;
  try {
    await stat(metaPath);
  } catch {
    throw new Error(`Could not find ${metaPath}. Does the folder exist locally?`);
  }

  console.log(colors.bold.yellow("Pushing folder..."));

  await pushFolder(

View on GitHub (pinned to e474e8803c)

Solutions

1. Read the appended e.body/e.message for the underlying HTTP status and fix that cause (auth, permission, validation).
2. Re-authenticate: run `wmill auth login` or refresh the workspace token (`wmill workspace add` with a fresh token).
3. Verify you can create folders in the UI — if not, request workspace admin/folder-create permissions.
4. Check connectivity to the instance (`curl <instance_url>/api/...`) and confirm the workspace name is correct.

Example fix

// before
throw Error(`Failed to create folder ${name}: ${e.body ?? e.message}`);

// user-side: authenticate first
// $ wmill auth login --token <TOKEN> --workspace main
// $ wmill folder push my_folder

// check auth and the folder name before pushing
if (!name || name.includes(' ')) throw new Error('invalid folder name');
// ensure `wmill workspace current` resolves and a valid token is set

try {
  await wmill.folder.push(name);
} catch (e) {
  if (/Failed to create folder/.test(e.message)) {
    const detail = e.message.split(':').slice(1).join(':');
    if (/401|403/.test(detail)) await reauth();
    else if (/409|exists/i.test(detail)) /* folder already exists — skip */ return;
    throw e;
  }
}

When it happens

Trigger: Calling `wmill folder push <name>` where the folder does not exist remotely, and the create-folder API call (wmill.createFolder) throws — e.g. HTTP 401/403 (bad token, insufficient permissions), 422 validation, or network errors. The catch block wraps any exception into this message.

Common situations: Expired or wrong-workspace API token; user lacking workspace admin rights to create folders; folder name violating naming rules; offline/VPN connectivity issues; pointing at the wrong instance URL.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• Failed to re-run job ${id}.
• Failed to push completed jobs: ${e}
• pointerErrors.join("\n")
• Invalid native trigger file path: ${filePath}. Expected form
• Not logged in. Please run 'wmill workspace add' first.

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/255412131a250c47. Report an issue: GitHub.