Skip to main content
The stars CLI reports every failure as a structured diagnostic: a stable code, a short explanation of why it happened, and — when there’s something you can do about it — a concrete fix. This page documents every code @wolfstar/cli can raise on its own; stars.config.* loading and validation errors are documented separately under Configuration Errors.

​
Exit codes

​
PREPARE_OUTDATED

The generated project files are out of date. Fix: run stars prepare to update them.

​
TSCONFIG_LEGACY_EXTENDS

A warning, not an error: the command keeps running. stars prepare, stars doctor, stars dev, stars build, and stars typecheck raise it when the project’s root tsconfig.json still extends ./.stars/tsconfig.json. From future.compatibilityVersion 6, stars prepare no longer writes that file. It writes .stars/tsconfig.app.json and .stars/tsconfig.node.json instead. Fix: replace the root tsconfig.json with a solution-style file that references the generated configs:
Or set future.compatibilityVersion to 5 to keep the single .stars/tsconfig.json. See Generated TypeScript configuration.

​
TYPECHECK_FAILED

stars typecheck found type errors in one or more projects. The message lists the failing projects, and the checker’s own output above it shows the errors. Fix: fix the reported type errors, then run stars typecheck again.

​
TYPECHECK_NO_PROJECT

stars typecheck found no tsconfig to check in the project root. Fix: create src/tsconfig.json or tsconfig.json, or set dev.typecheck.tsconfig.

​
DISCORD_TOKEN_MISSING

DISCORD_TOKEN is not set. Fix: set DISCORD_TOKEN in the environment or in the project’s .env file.

​
DISCORD_APPLICATION_ID_MISSING

The Discord application id is not set. Fix: set DISCORD_APPLICATION_ID (or APPLICATION_ID) in the environment or in the project’s .env file.

​
DISCORD_REQUEST_FAILED

Discord answered with an error status while the CLI was calling the Discord API (for example while pushing or listing commands). Fix: a 401 status means the token is wrong — check DISCORD_TOKEN. Any other status means the application id or the bot’s permissions are wrong.

​
BUILD_FAILED

The build step failed, optionally with the underlying build tool’s own error message attached. This is the one CLI error with its own exit code: 3.

​
COMMAND_NOT_FOUND

No deployed command, subcommand, or group matches the name(s) or path(s) passed to stars commands clean --name. Fix: run stars commands list to see what’s currently deployed.

​
ABORTED

An interactive prompt was cancelled.

​
CONFIRMATION_REQUIRED

stars commands delete refuses to delete commands without an explicit confirmation. Fix: pass --yes to delete them without prompting, or --name to pick a single command, when running from a script.

​
DEPLOY_CONFIRMATION_REQUIRED

stars commands deploy refuses to overwrite the deployed commands without a confirmation. It raises this outside a terminal, or with --json. Fix: pass --yes to deploy from a script or with --json.

​
COMMANDS_DIFFER

stars commands diff --check found deployed commands that differ from the ones the project defines. The message includes how many differ. Fix: run stars commands deploy to deploy them.

​
LOCAL_COMMANDS_UNAVAILABLE

stars commands diff or stars commands deploy could not read the commands the project defines. The message includes the reason, for example a project that is not built or a framework older than @wolfstar/http-framework 6.1. Fix: the message includes the fix for the reason it reports.

​
DOCTOR_FAILED

stars doctor found at least one failing check. The message includes how many checks failed, and the command exits with code 1. Fix: follow the fix stars doctor prints under each failing check.

​
UNKNOWN_SHELL

stars completions was given a shell it has no completions for. Fix: use one of bash, zsh, or fish.

​
INVALID_OPTION

A command was given an unknown value for one of its flags: --layout, --style, --port, --host, --port-conflict, or --level for stars dev, or --only for stars codegen. Fix: use one of the values the message lists. --layout accepts auto, dashboard, or panel. --style accepts nuxt-style, dashboard, or none. --port accepts an integer from 1 to 65535. --host accepts an IP address or hostname. --port-conflict accepts prompt, next, error, or continue. --level accepts trace, debug, info, warn, or error. --only accepts i18n or commands.

​
PORT_IN_USE

stars dev found the development listener port already occupied, and it couldn’t ask what to do. This happens with dev.portConflict: 'error' (or --port-conflict error), or with the default prompt policy in CI, with piped input, or with TERM=dumb. Fix: stop the other server, pick another port with --port <1..65535>, or set --port-conflict next or --port-conflict continue (dev.portConflict in stars.config). See Port conflicts.

​
PORT_CHECK_FAILED

stars dev couldn’t check whether the listener host and port are free, because binding them failed for another reason than the port being occupied (for example, a missing permission or an unknown address). The message includes the host, port, and bind error. Fix: check the local address (HTTP_ADDRESS or --host) and your permission to bind it, or pick another port with --port.

​
NO_AVAILABLE_PORT

With the next policy, or the “use the next available port” prompt choice, stars dev tried up to 100 ports above the occupied one and found none free. Fix: stop a server you no longer need, or pick another starting port with --port.

​
DEV_DIRECTORY_UNWRITABLE

Before building, stars dev couldn’t write to one of its output, generated-file, or log directories. The directory can’t be created or written, a file blocks its path, or no parent directory exists. The message names the path and the reason. Fix: use a writable directory, grant write and search access to it, or remove the file blocking it.

​
INVALID_THEME

stars dev was given a theme it doesn’t know. Fix: use one of the themes it lists as available.

​
CODEGEN_OUTDATED

Generated files (i18n types, etc.) are out of date. Fix: run stars codegen to update them.

​
CODEGEN_GENERATOR_DISABLED

stars codegen --only <generator> named a generator that is off in stars.config, so nothing would have been checked. Fix: turn codegen.<generator> on, or leave the generator out of --only.

​
DEPENDENCY_MISSING

A dependency the current configuration needs (for example tsdown or vite) isn’t installed in the project root. Fix: the message names the missing package and where to install it.

​
CODEGEN_FAILED

i18next-type-generator exited with a non-zero code, optionally with its stderr output attached.

​
MODULE_FAILED

A module listed in modules in stars.config could not be installed. The message carries the underlying ModuleError code and the module’s name. Exits with code 2. Fix: depends on the underlying code:
  • MODULE_LOAD_FAILED: install the module in the project, or fix its specifier in modules.
  • MODULE_INCOMPATIBLE: update the module or @wolfstar/http-framework so their versions match.
  • MODULE_INVALID: export the module with defineModule from @wolfstar/kit as the default export, and give its meta a name. A meta.configKey must be a non-empty string that is not a built-in stars.config key or used by another module, and the value under it must be an object.
  • MODULE_PLUGIN_INVALID: pass ctx.addPlugin a package specifier, an absolute path or a file: URL, and JSON-serialisable options.
  • MODULE_PIECES_INVALID: pass ctx.addPiecesDir an absolute path or a file: URL, such as new URL('./pieces', import.meta.url).
  • MODULE_HOOK_INVALID: use one of the client:* hook names, declare each name once per module, and give the hook by source (a package specifier, an absolute path, a file: URL, or { from, export }), not as a function.
  • MODULE_LOCALES_INVALID: pass ctx.addLocales an absolute path or a file: URL to a directory that exists and is readable when the module is set up.
  • Otherwise: fix the error the module threw (see the cause), or remove it from modules.

​
MODULES_PRELOAD_REQUIRED

A warning from stars build, stars prepare, and stars info. The project uses the tsc or none build tool and its modules add runtime plugins, pieces directories, locales, or client hooks. Those are registered through node --import, which only stars dev does for you. Fix: start the production bot with node --import ./.stars/modules.mjs <entry>. stars prepare and stars build write that file.

​
PLUGINS_NOT_REGISTERED

A warning from stars build, stars prepare, stars dev, stars info, and stars doctor. The project sets future.compatibilityVersion: 7, which registers only the modules in modules. An installed @wolfstar/plugin-* dependency that no module covers is no longer activated through its /register import, so it never runs. The message names those plugins. Fix: one of:
  • List the plugin in modules once its package exports a module, such as '@wolfstar/plugin-i18next/module'.
  • Import the plugin in the bot yourself.
  • Set future.compatibilityVersion back to 6.

​
VARLOCK_LOADER_IMPLICIT

A warning from stars prepare, stars build, stars dev, and stars info. The project has a varlock .env.schema and varlock is installed, so @wolfstar/env-utilities loads the environment through varlock. stars.config does not set env.loader or env.path. Fix: run stars doctor --fix to set env: { loader: 'varlock' }, or add it to stars.config by hand. See Fix the configuration.

​
VARLOCK_NOT_INSTALLED

A warning from stars prepare, stars build, stars dev, and stars info. The project has a varlock .env.schema, but varlock is not installed, so the bot loads the dotenv files instead. Fix: install varlock (for example pnpm add varlock), or remove the .env.schema.