Skip to main content
Every way stars.config.* can fail to load or validate is a structured diagnostic exported from @wolfstar/http-framework/config as configDiagnostics. @wolfstar/cli renders these the same way as its own CLI errors and exits with code 2 for all of them, except warnings such as COMPATIBILITY_VERSION_EOL.

​
ROOT_NOT_FOUND

The project root does not exist. Fix: point root to an existing directory, relative to the configuration file.

​
PACKAGE_JSON_INVALID

The project’s package.json failed to parse. Fix: fix the JSON syntax of the package.json file.

​
ENTRY_NOT_FOUND

The entry file does not exist. Fix: point entry to the file that starts the bot, relative to the project root.

​
ENTRY_DEFAULT_NOT_FOUND

Could not find an entry file in the project root under any of the default names. Fix: set entry in the configuration, or create one of the default entry files.

​
INVALID_BUILD_TOOL

build.tool is set to an unknown value. Fix: use one of 'tsdown', 'tsc', 'vite', 'none' or 'auto'.

​
EXPERIMENTAL_BUILD_TOOL

The selected build tool is experimental. Fix: set the matching experimental.* flag to true to opt in.

​
BUILD_TOOL_REQUIRED

The entry file is TypeScript but build.tool is 'none'. Fix: set build.tool to 'tsdown' or 'tsc', or point entry to a JavaScript file.

​
TSCONFIG_EXPLICIT_NOT_FOUND

The tsconfig.json file pointed to explicitly by the configuration does not exist. Fix: point that option to an existing tsconfig.json, relative to the project root.

​
TSCONFIG_NOT_FOUND

Could not find a tsconfig.json in the project root. Fix: create src/tsconfig.json or tsconfig.json, or set the suggested option explicitly.

​
TSDOWN_OPTIONS_REQUIRE_TSDOWN

tsdown options were set but build.tool isn’t 'tsdown'. Fix: set build.tool to 'tsdown', or remove the tsdown options.

​
VITE_OPTIONS_REQUIRE_VITE

vite options were set but build.tool isn’t 'vite'. Fix: set build.tool to 'vite' with experimental.enableVite, or remove the vite options.

​
TSDOWN_CONFIG_FILE_UNSUPPORTED

A tsdown config file exists but isn’t used at the project’s current compatibility version. Fix: move its options into the tsdown configuration option, drop the config file, or lower future.compatibilityVersion to the legacy version.

​
INVALID_TYPE

An option was set to a value of the wrong type. Fix: the message names the option, the type it expects, and the value it actually received.

​
INVALID_COMPATIBILITY_VERSION

future.compatibilityVersion is set to an unknown version. Fix: use one of the supported versions (3, 4, 5, or 6). Version 6 carries today’s defaults.

​
COMPATIBILITY_VERSION_EOL

future.compatibilityVersion is set to 3, which is end-of-life and will be removed in the next major. This is a warning: the configuration still loads, and every command prints it. stars info shows it next to the version in effect. Fix: move the options of your tsdown.config.* into tsdown in stars.config, delete that file, then set future.compatibilityVersion to 6 (or remove it).

​
UNKNOWN_OPTION

The configuration contains an option name @wolfstar/http-framework doesn’t recognize. A top-level key that is not built in is checked later. The stars commands report it once the modules are set up, if no installed module claims it as its meta.configKey. The check also runs when modules is empty. loadStarsConfig on its own does not report such keys. Fix: the message lists the known options for that section. Check for a typo. For a top-level key, the list includes the keys claimed by installed modules. The hint asks you to check that the module is listed in modules and declares the key as its configKey.

​
UNKNOWN_HOOK

hooks contains a hook name the stars CLI doesn’t recognize. stars rejects it rather than registering a hook that never runs. Fix: the message lists the known hooks (config:resolved, env:options, prepare:before, prepare:done, builder:created, tsdown:options, build:before, build:done, dev:start, dev:restart, dev:close). Check for a typo in the full name or the namespaced form.

​
EXPERIMENT_REQUIRED

An option needs an experimental.* flag that isn’t set. Fix: set the required flag to true as well, or drop the option that needs it.

​
IMPORTS_REQUIRE_TSDOWN

imports was set but build.tool isn’t 'tsdown'. Fix: set build.tool to 'tsdown', or remove imports (or set it to false).

​
ENV_REQUIRES_ENV_UTILITIES

env is enabled, but the project does not depend on @wolfstar/env-utilities. Fix: install it with pnpm add @wolfstar/env-utilities, or set env to false.

​
LOCALES_NOT_FOUND

codegen.i18n.locales points to a directory that does not exist. Fix: point it to the base locale directory, relative to the project root.

​
INVALID_PORT

stars dev resolved a development listener port that isn’t an integer from 1 to 65535. The port is read from HTTP_PORT or PORT in dev.env, the process environment, or the project’s .env files. It is only checked when stars dev starts. Fix: set HTTP_PORT or PORT (including dev.env and .env files) to an integer from 1 to 65535.

​
ENV_EXPANSION_FAILED

Expanding variable references (such as HTTP_PORT=${PORT}) in an env file went deeper than 100 levels or produced a value larger than 1 MiB. Fix: simplify the environment variable references.

​
INVALID_URL

An option that expects a URL received a value that isn’t a valid URL. Fix: the message includes what a valid value looks like for that option.

​
TUNNEL_URL_NOT_HTTPS

The tunnel URL isn’t https. Fix: Discord only accepts an https interactions endpoint.

​
TUNNEL_OPTION_CONFLICT

A dev.tunnel option does not apply to the rest of the tunnel configuration. This happens when:
  • dev.tunnel.provider or dev.tunnel.domain is set next to dev.tunnel.url. A URL you already serve has no tunnel provider.
  • dev.tunnel.domain is set without provider: 'ngrok'. Only ngrok can bind a reserved domain, and cloudflared is the default provider.
The message names the option and the reason. Fix: remove provider or domain, or remove url to let the CLI open the tunnel. For a reserved domain, set dev.tunnel.provider to 'ngrok':

​
INVALID_CHOICE

An option limited to a fixed set of values received an unknown one: dev.layout, dev.logs.levels, dev.commands.refresh, or dev.tunnel.provider. The message names the option path and the value it received. Fix: use one of the values the message lists. For example, dev.layout accepts 'auto', 'dashboard', or 'panel', and dev.tunnel.provider accepts 'cloudflared' or 'ngrok'.

​
INVALID_TYPECHECKER

The configured type checker is set to an unknown value. Fix: use one of 'tsc', 'golar', 'tsz' or 'auto'.

​
CONFIG_NOT_FOUND

No stars.config.* file was found. Fix: pass an existing file to --config, or create one of the recognized config file names in the current directory.

​
CONFIG_LOAD_FAILED

The configuration file failed to load. Fix: the file must be valid TypeScript/JavaScript and export the configuration as its default export.

​
CONFIG_NOT_OBJECT

The configuration file’s default export isn’t an object. Fix: use export default defineConfig({ ... }) from @wolfstar/http-framework/config.