Skip to main content

Troubleshooting

Unknown short flag "-x"​

ForgeLoop supports only a small short-flag set:

  • -h (--help)
  • -V (--version)
  • -y (--yes)
  • -d <path> (--dir <path>)

Any other short flag (for example -x) is rejected.

init requires a project name in non-interactive mode​

In CI, Docker, or any non-interactive run, pass the name after init:

npx forgeloop init my-bot --yes

Using create-forgeloop, a bare project name is already treated as init my-bot.

Git, Docker, CI, or install skipped in CI​

Boolean flags --git, --docker, --ci, --install are only prompted in interactive mode. In non-TTY sessions they default to false unless you pass the flag explicitly:

npx forgeloop init my-bot --yes --git --install

Selects like --language still use defaults when omitted in non-interactive mode (ts, modular, npm, etc.).

Basic preset: add / commands fails​

basic keeps commands and events inline in src/index.*. Use modular or advanced if you need:

  • forgeloop add ...
  • forgeloop remove ...
  • forgeloop commands list|deploy

The CLI error text states this explicitly.

Commands deploy: missing GUILD_ID or wrong sync target​

  • Guild sync (development default, or --guild) requires GUILD_ID in .env or the environment.
  • Global sync happens when NODE_ENV=production by default, or explicitly with --global.

See commands and Sync application commands.

Commands list/deploy: command module import errors​

commands list and commands deploy import command modules from src/commands. Run from a machine with dependencies installed (node_modules present). Missing packages surface as:

Failed to load application command modules: …

No ForgeLoop config found​

The CLI expects forgeloop.config.mjs in the project root (or the directory given by --dir).

Manifest load errors​

  • Invalid or missing exports in .mjs config → load error with the underlying Node message.

Doctor reports problems​

forgeloop doctor runs grouped checks (config, structure, environment, dependencies, Discord command loading for modular/advanced, and optional network/tooling). Each finding includes suggested fixes.

  • Missing scaffold files — restore them or align the manifest with what is on disk (e.g. disable a feature you removed manually).
  • .env / secrets — use --fix to copy .env.example → .env when missing, then fill real values.
  • Errors vs warnings — only errors fail the run by default; use --strict in CI to fail on warnings too.
  • JSON for support — run forgeloop doctor --json and attach the report (redact secrets).

Still stuck? Open an issue on GitHub with the exact command, ForgeLoop version, and redacted error output.